Using R Markdown with RStudio

R Markdown enables easy authoring of reproducible web reports from R. It offers:

• Easy creation of web reports from R that can be automatically regenerated whenever underlying code or data changes.
• A highly accessible syntax (markdown) which lower the barriers to entry for reproducible research.
• Output of a standalone HTML file (with images embedded directly in the file) that is easy to share using email, Dropbox, or by deploying to a web server.
• Support for publishing dynamic and interactive web content.

This article includes an overview of how to use R Markdown within RStudio. For more specific details on syntax and implementation, see the R Markdown article.

Markdown Basics

Markdown is a simple markup language designed to make authoring web content easy for everyone. Rather than writing HTML and CSS code, 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 as an HTML file on the right:

R Markdown Documents

To work with R Markdown (.Rmd) files in RStudio you first need to ensure that the knitr package (version 0.5 or later) in installed.

To create a new R Markdown file, go to File | New | and select R Markdown. A new file is create with a default template to get you oriented:

Note that the toolbar provides some useful tools for working with R Markdown:

• Quick Reference — Click the MD toolbar button to open a quick reference guide for Markdown.
• Knit HTML — Click to knit the current document to HTML, see the Knitting to HTML section below for more details.
• Run — Run the current line or selection of lines in the console. This allows running R code inside a code chunk similar to a normal R source file.
• Chunks — The chunks menu provides assistance with inserting, running, and chunk navigation. See the Chunk Menu and Options section below for more details.

Embedding R Code Chunks

Within an R Markdown file, R Code Chunks can be embedded using the native Markdown syntax for fenced code regions:

```{r chunkLabel}
# R code
```

For example, the following code chunk computes a data summary and renders a plot as a PNG image. It then embeds the results within a standalone HTML file:

Embedding 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:

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 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.

Knitting to HTML

Click the Knit HTML toolbar button (or use the Cmd+Shift+H shortcut) to process an R Markdown file into a web page. This runs knit on the Rmd file to create a Markdown file, evaluating all R code and results as specified. Note that for reproducibility purposes, the knit runs in a separate process and environment (rather than using the current workspace). This is to ensure the script will always produce the same result and not be effected by (or pollute) your regular R environment. Finally, the generated Markdown file is converted into HTML and shown in a separate preview window.

The HTML file which is generated by invoking Knit HTML is a standalone web page. This means that images, CSS, etc. are embedded within the HTML file so it can be shared without needing to package up any additional files. You can attach the HTML file to an email, share it using Dropbox, or deploy it to a web server as a single HTML file.

Navigating Between Chunks

A popup navigation menu is located at the bottom of the editor based on the chunk labels (optional) in your Rmd file. This makes editing and navigating between chunks easy. The following screenshot shows an example of this chunk navigation menu.

Using the Chunk Menu

The chunk Menu makes it easy to insert new chunks and execute R code from within an R Markdown document.

• Insert Chunk — Inserts the basic syntax for an embedded R code chunk.
• Jump To... — Opens the Chunk Navigation Menu to jump to a specific code chunk.
• Run Current/Next Chunk — Runs the current (or next) code chunk based on the cursor position. You can use this to iteratively step through code chunks one-by-one to test your R code. This interacts with the console and acts upon the current global environment.
• Run All — Run all R code chunks in the current document. This is analogous to sourcing the file which results from the stangle of an Rnw file.

Customizing Chunk Options

You can apply knitr options to each code chunk individually or globally. When typing chunk options, code-completion is enabled to help recall and complete option names and values. See the example document on customizing chunk options or see the knitr package for a full list of chunk options.

Gallery of Examples

Related Topics

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