R Markdown is an authoring format that enables easy creation of dynamic documents, presentations, and reports from R. It combines the core syntax of markdown (an easy-to-write plain text format) with embedded R code chunks that are run so their output can be included in the final document. R Markdown documents are fully reproducible (they can be automatically regenerated whenever underlying R code or data changes).

This website describes R Markdown v2, a next generation implementation of R Markdown based on knitr and pandoc. This implementation brings many enhancements to R Markdown, including:

Note that PDF output (including Beamer slides) requires an installation of TeX. On Windows, MiKTeX should be used rather than TeX Live.

Installing R Markdown

You can use R Markdown either through the integrated support provided by RStudio or by directly using the rmarkdown package:

  1. RStudio — Install the latest version of RStudio (v0.98.932).

  2. Other environments — Install the rmarkdown package.

Quick Tour

Markdown Basics

Markdown is a simple formatting language designed to make authoring content easy for everyone. Rather than writing complex markup code (e.g. HTML or LaTeX), Markdown enables the use of a syntax much more like plain-text email. For example the file on the left shows basic Markdown and the resulting output on the right:

Markdown Overview

R Code Chunks

Within an R Markdown file, R Code Chunks can be embedded using the native Markdown syntax for fenced code regions. For example, the following code chunk computes a data summary and renders a plot as a PNG image:

Markdown Chunk

Inline R Code

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

Markdown Inline

Results in this output: “I counted 2 red trucks on the highway.”

Embedding 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 white space adjacent to the $ delimiters)
  • $$ equation $$ for display equations
  • <math ...> </math> for MathML equations.

For example:

Equation Inline

Rendering Output

There are two ways to render an R Markdown document into it’s final output format. If you are using RStudio, then the “Knit” command (Ctrl+Shift+K) will render the document and display a preview of it.

If you are not using RStudio then you simply need to call the rmarkdown::render function, for example:

rmarkdown::render("input.Rmd")

Note that in the case using the “Knit” button in RStudio the basic mechanism is the same (RStudio calls the rmarkdown::render function under the hood).

Output Options

R Markdown documents can contain a metadata section that includes both title, author, and date information as well as options for customizing output. For example, this metadata included at the top of an Rmd file adds a table of contents and chooses a different HTML theme:

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
---

R Markdown has built in support for several output formats (HTML, PDF, and MS Word documents as well as Beamer presentations). These formats can also be specified in metadata, for example:

---
title: "Sample Document"
output:
  pdf_document:
    toc: true
    highlight: zenburn
---

If you aren’t specifying format options you can also just use a simple format name:

---
title: "Sample Document"
output: pdf_document
---

Multiple formats can be specified in metadata:

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
  pdf_document:
    toc: true
    highlight: zenburn
---

If you are using rmarkdown::render then you can pass a format name to render to select from the available formats. For example:

render("input.Rmd", "pdf_document")

You can also render all formats defined in an input file with:

render("input.Rmd", "all")

Learning More

With the basics described above you can get started with R Markdown right away. To learn more see:

For even more in-depth documentation see:

See also the R Markdown developer documentation including:

comments powered by Disqus