R Markdown
from

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 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:
    <!--html_preserve-->
        <strong>This will render as HTML not preformatted text</strong>
    <!--/html_preserve-->

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

  2. A varation of #2, use the htmltools 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. 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 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 package.