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).
Note that PDF output (including Beamer slides) requires an installation of TeX.
You can use R Markdown either through the integrated support provided by RStudio or by directly using the rmarkdown package:
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:
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:
You can also evaluate R expressions inline by enclosing the expression within a single back-tick qualified with ‘r’. For example, the following code:
Results in this output: “I counted 2 red trucks on the highway.”
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.
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:
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).
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:
You can also render all formats defined in an input file with:
With the basics described above you can get started with R Markdown right away. To learn more see:
Markdown Basics, which describes the most commonly used markdown constructs.
R Code Chunks, which goes into more depth on customizing the behavior of embedded R code.
R Markdown Cheat Sheet (PDF), a quick guide to the most commonly used markdown syntax, knitr options, and output formats.
R Markdown Reference Guide (PDF), a more comprehensive reference guide to markdown, knitr, and output format options.
Bibliographies and Citations, which describes how to include references in R Markdown documents.
Compiling Notebooks, which describes how to compile HTML, PDF, or MS Word notebooks from R scripts.
For even more in-depth documentation see:
The website for the knitr package. Knitr is an extremely powerful tool for dynamic content generation and the website has a wealth of documentation and examples to help you utilize it to its full potential.
The full specification of Pandoc Markdown, which describes all of the markdown features and syntax available within R Markdown documents.
If you are migrating documents from R Markdown v1 or wish to continue using RMarkdown v1 see the article on Migrating from R Markdown v1.
See also the R Markdown developer documentation including: