R Markdown

Overview

R Markdown is a format that enables easy authoring of reproducible web reports from R. It combines the core syntax of Markdown (an easy-to-write plain text format for web content) with embedded R code chunks that are run so their output can be included in the final document.

The concept of R Markdown is similar to Sweave (a system built-in to R for combining R with LaTeX). In Sweave, Rnw files are "weaved" into TeX files that are then compiled into PDFs. In R Markdown, Rmd files are similarly "weaved" into plain markdown (.md) files that are then compiled into HTML documents.

The R Markdown syntax is described in detail below. At a high-level it is a combination of the following:

• The core Markdown syntax
• The ability to embed R code and the results of its execution
• Additional extensions provided by the Sundown library
• Support for LaTeX and MathML equations
• Bundling of images within generated HTML files

Implementation

The implementation of R Markdown is provided by two packages:

• knitr — Weaves Rmd files into plain markdown (.md) files
• markdown — Converts markdown files into HTML documents

For example, to run the R code chunks inside an Rmd file and then convert the resulting markdown file into HTML you would execute the following:

library(knitr)
library(markdown)
knit("Foo.Rmd")
markdownToHTML("Foo.md", "Foo.html")

Note that this can also be accomplished in one step by calling knitr::knit2html. However, the fact that converting from Rmd to HTML is broken into two steps allows for the use of alternate markdown rendering programs (e.g. Pandoc).

RStudio also implements support for rendering R Markdown files into HTML using the Knit HTML commands. This produces a result equivalent to the above code.

Syntax

The following is a detailed description of the R Markdown syntax. Note that the first two sections covering Core Markdown and R Code Chunks are always applicable. The remaining sections apply to the rendering of markdown to HTML as implemented by RStudio and the markdown package. If you are using an alternate markdown program such as Pandoc please consult its documentation for information on comparable extensions.

Core Markdown

The core markdown syntax defines plain-text formatting commands for a wide variety of constructs including headers, phrase emphasis, ordered and unordered lists, links, images, and inline code. R Markdown implements all of the core markdown syntax (with two exceptions noted below in the Github/Sundown Extensions section).

Please reference the core markdown syntax definition for a detailed description of supported elements.

Embedded R Code

Within an R Markdown file, R code chunks can be embedded using fenced code regions:

```{r}
1 + 1
```

R code chunks can also have a label and specify processing options:

```{r md-cars-scatter, message=FALSE, fig.width=7, fig.height=5}
library(ggplot2)
qplot(hp, mpg, data=mtcars)+geom_smooth() 
```

You can also evaluate R expressions inline by enclosing the expression within a single back-tick qualified with 'r'. For example:

I counted `r 1 + 1` red trucks on the highway.

When R code is displayed in the resulting HTML file, it is given a distinct background color and syntax highlighted. Textual output resulting from R code is shown within a bordered frame.

Sundown Extensions

The markdown package uses the Sundown library for rendering markdown to HTML (Sundown is a project maintained by Github). Sundown supports core markdown, a set of extensions known as Github flavored markdown, as well several other extensions.

The Github flavored markdown extensions include:

• Multiple underscores in words (e.g. perform_complicated_task) are not treated as formatting
• URLs are automatically linked
• Fenced code regions using ```

Additional extensions include:

• Pandoc title blocks and YAML front-matter at the top of documents is ignored
• Support for tables using the syntax defined by PHP Markdown Extra.
• Superscripts (e.g. superscript^2)
• Strikethrough (e.g. ~~strikethrough~~)

Finally, selected ASCII character sequences are converted into typographic HTML entities:

• Straight quotes ( " and ' ) into “curly” quotes
• Backtick quotes (``like this'') into “curly” quotes
• Dashes (“--” and “---”) into en- and em-dash entities
• Three consecutive dots (“...”) into an ellipsis entity
• Fractions 1/4, 1/2, and 3/4 into ?, ?, and ?
• Symbols (c), (tm), and (r) into ?, ?, and ?

LaTeX and MathML Equations

You can embed LaTeX or MathML equations in R Markdown files using the following syntax:

• $equation$ for inline equations (note there must not be whitespace adjacent to the $ delimiters)
• $$ equation $$ for display equations
• <math ...> </math> for MathML equations.

The article on Equations in R Markdown includes more detailed information on embedded equations.

Image Bundling

When converting from markdown to HTML, images that are referenced using relative hrefs are bundled directly into the generated HTML file. This creates a standalone web page that can be shared without needing to package up any additional files. You can attach the HTML file to an email, share it using a public folder, or deploy it to a web server as a single HTML file.

Image bundling is performed by base64 encoding the image and then inlining the encoded image using a data URI.

Text Encoding

The Sundown library reads and writes content using UTF-8 encoding. It is therefore most convenient to use UTF-8 as the encoding for Rmd files. Note that RStudio supports the use of other encodings for Rmd files (it converts them to UTF-8 prior to sending them to Sundown) however if you are using the markdown package directly you'll need to perform this conversion manually.

Related Topics

• Using R Markdown
• Equations in R Markdown
• Customizing Markdown Rendering
• Creating Notebooks from R Scripts