The current implementation of R Markdown (v2) is an evolution of the original implementation, which was not based on pandoc but rather the 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.
The following changes to markdown syntax were made in R Markdown v2:
$latex <equation>$) is no longer supported.
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
If you are creating an R function that generates HTML there are a number of ways to avoid this behavior:
<!--html_preserve--> <strong>This will render as HTML not preformatted text</strong> <!--/html_preserve-->
Generate HTML that does not indent tags at the beginning of lines.
A varation of #2, use the htmltools package to generate HTML (which will print it’s 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).
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.
One other important change relates to the use of the knitr 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.
cache.path option, the rmarkdown package has also modifies a few other default chunk options in knitr when calling
fig.path: the default value in knitr is
figure/, and it has been changed to
formatis the output format, such as
error: it was changed from
FALSE, meaning that knitr will stop on error by default;
There are some other subtle changes, such as
2 for the HTML output),
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.
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 package.