Distill for R Markdown

Scientific and technical writing, native to the web

JJ Allaire https://github.com/jjallaire (RStudio)https://www.rstudio.com , Rich Iannone https://github.com/rich-iannone (RStudio)https://www.rstudio.com , Yihui Xie https://github.com/yihui (RStudio)https://www.rstudio.com
September 10, 2018

Distill for R Markdown is a web publishing format optimized for scientific and technical communication. Distill articles include:

Distill for R Markdown is based on the Distill web framework, which was originally created for use in the Distill Machine Learning Journal (Carter, Olah, and Satyanarayan 2016). Distill for R Markdown combines the technical authoring features of Distill with R Markdown, enabling a fully reproducible workflow based on literate programming (Knuth 1984).


To create an R Markdown document that uses the Distill format, first install the development version of the distill R package from GitHub:


Using Distill for R Markdown requires Pandoc v2.0 or higher. If you are using RStudio then you should use RStudio v1.2.718 or higher (which comes bundled with Pandoc v2.0).

You can download the latest version of RStudio at https://www.rstudio.com/products/rstudio/download/.

Creating an article

Use the New R Markdown dialog within RStudio to create a new Distill article:

You can also create a new Distill article from the command line with:

draft("article.Rmd", "distill_article", package = "distill")

Distill articles use distill::distill_article as their output format, and typically include title, description, date, author/affiliation, and bibliography entries in their YAML front-matter:

title: "Distill for R Markdown"
description: | 
  Scientific and technical writing, native to the web
date: May 4, 2018
  - name: "Yihui Xie"
    url: https://github.com/yihui
    affiliation: RStudio
    affiliation_url: https://www.rstudio.com
    orcid_id: 0000-0003-0645-5666
  - name: "JJ Allaire"
    url: https://github.com/jjallaire
    affiliation: RStudio
    affiliation_url: https://www.rstudio.com
  - name: "Rich Iannone"
    url: https://github.com/rich-iannone
    affiliation: RStudio
    affiliation_url: https://www.rstudio.com
bibliography: biblio.bib
output: distill::distill_article

Author entries must have at least name and url specified (the affiliation fields are optional). Specify an author’s Orcid ID using the orcid_id field.

The article’s description and author bylines are automatically rendered as part of the title area of the document.

The date field should be formatted as month, day, year (various notations are supported as long as the components appear in that order).

The bibliography field is used to provide a reference to the Bibtex file where all of the sources cited in your article are defined. The citations section describes how to include references to these sources in your article.


Distill provides a number of options for laying out figures within your article. By default figures span the width of the main article body:

However, some figures benefit from using additional horizontal space. In this cases the layout chunk option enables you to specify a wide variety of other layouts.

For example, if we wanted to display a figure a bit outside the bounds of the article text, we could specify the l-body-outset layout via the layout chunk option:

```{r, layout="l-body-outset", fig.width=6, fig.height=1.5}
ggplot(diamonds, aes(carat, price)) + geom_smooth() +
  facet_grid(~ cut)

Note that when specifying an alternate layout you should also specify an appropriate fig.width and fig.height for that layout. These values don’t determine the absolute size of the figure (that’s dynamic based on the layout) but they do determine the aspect ratio of the figure.

See the documentation on figure layout for details on additional layout options.

The examples above are based on conventional R plots. Distill articles can also incorporate diagrams and interactive visualizations based on JavaScript and D3.


There are a number of options available for HTML display of data frames within Distill articles. Here, we use the paged_table() function to display a page-able view of the mtcars dataset built in to R:

```{r, layout="l-body-outset"}

Note that we used layout="l-body-outset" to cause the table to occupy slightly more horizontal space than the article text. All of available figure layout options work as expected for tables.

See the documentation on table display for details on the various techniques available for rendering tables.


Inline and display equations are supported via standard markdown MathJax syntax. For example, the following LaTeX math:

\sigma = \sqrt{ \frac{1}{N} \sum_{i=1}^N (x_i -\mu)^2}

Will be rendered as:

\[ \sigma = \sqrt{ \frac{1}{N} \sum_{i=1}^N (x_i -\mu)^2} \]


Bibtex is the supported way of making academic citations. To include citations, first create a bibtex file and refer to it from the bibliography field of the YAML front-matter (as illustrated above).

For example, your bibliography file might contain:

  title = {Dynamic Documents with R and knitr},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2015},
  edition = {2nd},
  note = {ISBN 978-1498716963},
  url = {http://yihui.name/knitr/},

Citations are then used in the article body with standard R Markdown notation, for example: [@xie2015] (which references an id provided in the bibliography). Note that multiple ids (separated by semicolons) can be provided.

The citation is presented inline like this: (Xie 2015). If you have an appendix, a bibliography is automatically created and populated in it.

See the article on citations for additional details on using citations, including how to provide the metadata required to make your article more easily citable for others.

Footnotes and asides

Footnotes use standard Pandoc markdown notation, for example ^[This will become a hover-able footnote]. The number of the footnote will be automatically generated.1

You can also optionally include notes in the gutter of the article (immediately to the right of the article text). To do this use the <aside> tag.

This content will appear in the gutter of the article.

You can also include figures in the gutter. Just enclose the code chunk which generates the figure in an <aside> tag:

ggplot(mtcars, aes(hp, mpg)) + geom_point() + geom_smooth()

Table of contents

You can add a table of contents using the toc option and specify the depth of headers that it applies to using the toc_depth option. For example:

title: "Distill for R Markdown"
description: | 
  Scientific and technical writing, native to the web
    toc: true
    toc_depth: 2

If the table of contents depth is not explicitly specified, it defaults to 3 (meaning that all level 1, 2, and 3 headers will be included in the table of contents).

Code blocks

Syntax highlighting is provided for knitr code chunks. Note that by default the Distill format does not display the code for chunks that are evaluated to produce output (knitr option echo = FALSE).

The echo = FALSE default reflects the fact that Distill articles are often used to present the results of analyses rather than the underlying code. To display the code that was evaluated to produce output you can set the echo chunk option to TRUE:

```{r, echo=TRUE}
1 + 1

To include code that is only displayed and not evaluated specify the eval=FALSE option:

```{r, eval=FALSE, echo=TRUE}
1 + 1

There are a number of default values that Distill establishes for knitr chunk options (these defaults also reflect the use case of presenting results/output rather than underlying code):

Option Value Comment
echo FALSE Don’t print code by default.
warning FALSE Don’t print warnings by default.
message FALSE Don’t print R messages by default.
comment NA Don’t preface R output with a comment.
R.options list(width = 70) 70 character wide console output.

Keeping R code and output at 70 characters wide (or less) is recommended for readability on a variety of devices and screen sizes.

As illustrated above, all of these defaults can be overridden on a chunk-by-chunk basis by specifying chunk options.

You can also change the global defaults using a setup chunk. For example:

```{r setup, include=FALSE}
  echo = TRUE,
  warning = TRUE,
  message = TRUE,
  comment = "##",
  R.options = list(width = 60)


Appendices can be added after your article by adding the .appendix class to any level 1 or level 2 header. For example:

## Acknowledgments {.appendix}

This is a place to recognize people and institutions. It may also be a good place
to acknowledge and cite software that makes your work possible.

## Author Contributions {.appendix}

We strongly encourage you to include an author contributions statement briefly 
describing what each author did.

Footnotes and references will be included in the same section, immediately beneath any custom appendices.


Distill for R Markdown builds on the work of many individuals and projects. Shan Carter, Ludwig Schubert, and Christopher Olah created the Distill web framework. John MacFarlane created the Pandoc universal markup converter. Davide Cervone and Volker Sorge created the MathJax library for rendering mathematical notation on the web. Mike Bostock created the D3 library for producing dynamic, interactive data visualizations for the web. We are grateful for the spirit of generosity that moved these individuals to create high-quality open source software for the benefit of all.

Carter, Shan, Chirs Olah, and Arvind Satyanarayan. 2016. “Distill.” Distill Working Group. https://doi.org/10.23915/distill.

Knuth, Donald E. 1984. “Literate Programming.” The Computer Journal 27 (2): 97–111.

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. http://yihui.name/knitr/.

  1. This will become a hover-able footnote↩︎



If you see mistakes or want to suggest changes, please create an issue on the source repository.


Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/rstudio/distill, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".


For attribution, please cite this work as

Allaire, et al. (2018, Sept. 10). Distill for R Markdown. Retrieved from https://rstudio.github.io/distill

BibTeX citation

  author = {Allaire, JJ and Iannone, Rich and Xie, Yihui},
  title = {Distill for R Markdown},
  url = {https://rstudio.github.io/distill},
  year = {2018}