---
title: "Migrating from R Markdown v1"
output:
  html_document:
    toc_float: false
---

## Changes in v2

The current implementation of R Markdown (v2) is an evolution of the original implementation, which was not based on pandoc but rather the [markdown](https://github.com/rstudio/markdown) package.  Moving to pandoc brings many new features to R Markdown however carries some minor incompatibilities with the previous implementation that are described below.

### Markdown Syntax

The following changes to markdown syntax were made in R Markdown v2:

1. The syntax for superscript now requires a closing ^ (e.g. `superscript^2^`).
2. The WordPress-style LaTeX equation syntax (e.g. `$latex <equation>$`) is no longer supported.
3. Markdown is rendered even if it's contained within HTML tags.

### Preserving Generated HTML

The change to render markdown within HTML tags has consequences for R functions that generate HTML for inclusion in a markdown document. The markdown processor considers any text that is indented 4 spaces to be preformatted text. This means that if you indent generated HTML tags 4 spaces they will be output as preformatted (i.e. within a `<pre>` tag). 

If you are creating an R function that generates HTML there are a number of ways to avoid this behavior:

1. Enclose the HTML in a special comment that indicates that no markdown processing should occur:

<pre>
    &lt;!--html_preserve--&gt;
        &lt;strong&gt;This will render as HTML not preformatted text&lt;/strong&gt;
    &lt;!--/html_preserve--&gt;
</pre>

2. Generate HTML that does not indent tags at the beginning of lines.

3. A varation of \#2, use the [**htmltools**](http://cran.r-project.org/web/packages/htmltools/index.html) package to generate HTML (which
will print its output by default without indentation).

If you are a user of an R package that is generating HTML that includes indentation you can temporarily workaround the problem by rendering your documnent with rmarkdown v1 (see section below on [Continuing to Use v1]).

### The knitr Package

R Markdown v2 no longer attaches the **knitr** package by default, i.e. it does not do `library(knitr)` before an R Markdown document is compiled (whereas v1 does), and **knitr** is only _loaded_ but not _attached_. As a result, you may see an error message like `object 'opts_chunk' not found` (or other objects in **knitr** not found). Not attaching a package makes the work space cleaner. If you only need to use a small number of objects in a package occasionally, you are recommended to use the `::` operator, e.g. `knitr::opts_chunk`. However, sometimes we may need to a lot of objects in a package, and it will be cumbersome to type `package::` again and again. In this case, you can attach the package to the current R session explicitly, e.g. `library(knitr)`.

### Knitr Caching

One other important change relates to the use of the [knitr cache](http://yihui.name/knitr/demo/cache/). When R Markdown knits documents it explicitly configures the knitr cache to use a directory based on the name of the input file (e.g. `inputfile_cache`). If you are setting an explicit cache directory within your document (e.g. via `opts_chunk$set(cache.path = ...))`) you should remove this code and rely on R Markdown to set the cache directory.

### Other knitr Options

Besides the `cache.path` option, the rmarkdown package has also modifies a few other default [chunk options](http://yihui.name/knitr/options) in knitr when calling `rmarkdown::render()`, including

- `fig.path`: the default value in knitr is `figure/`, and it has been changed to `inputfile_files/figure-format/`, where `format` is the output format, such as `html`;
- `error`: it was changed from `TRUE` to `FALSE`, meaning that knitr will stop on error by default;

There are some other subtle changes, such as `fig.retina` (from `NULL` to `2` for the HTML output), `fig.width` and `fig.height` (depending on the document output format). You can print `knitr::opts_chunk$get()` in an R Markdown document to see the default chunk options configured by rmarkdown.

## Continuing to Use v1

If you are using RStudio you can force RStudio to render documents using R Markdown v1 by adding a special comment to your source file:

<pre>&lt;!-- rmarkdown v1 --&gt;</pre>

For rendering R Markdown v1 documents outside of RStudio you can continue to use the [markdown](https://github.com/rstudio/markdown) package.

