--- 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 $`) 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 `
` 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:

    <!--html_preserve-->
        <strong>This will render as HTML not preformatted text</strong>
    <!--/html_preserve-->
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:
<!-- rmarkdown v1 -->
For rendering R Markdown v1 documents outside of RStudio you can continue to use the [markdown](https://github.com/rstudio/markdown) package.