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:
superscript^2^
).$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 <pre>
tag).
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. library(knitr)
.
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.
Besides the cache.path
option, the rmarkdown package has also modifies a few other default chunk 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.
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.