Dynamic Documents with R Markdown

Yihui Xie, Karl Broman, and Ian Lyttle

2016/06/27 @ Stanford, useR! 2016


Slides and examples

Part I: An introduction to R Markdown

No cut-and-paste

Solution: Automation! Automation! Automation!

Basic ideas of dynamic documents


Original Markdown

Pandoc’s Markdown

The rmarkdown package

Using rmarkdown

Basic format options

Customize CSS for HTML output

Customize LaTeX preamble for PDF output

Pandoc templates

If none of the existing options can give you the output you desire, you can simply replace the Pandoc template, which allows you to customize everything.

When Pandoc converts Markdown to another output format, it uses a template under the hood (specified via the --template option of Pandoc, or template argument of most output format functions in rmarkdown).

The template is a plain text file that contains some variables of the form $variable$. These variables will be replaced by their values generated by Pandoc.

A minimal HTML template:



Variables are typically read from the YAML metadata of the Markdown document, such as $title$, e.g.

title: A _Nice_ Markdown Document

The value of a variable can be different for different output formats, e.g. $title$ is A \emph{Nice} Markdown Document when the output format is LaTeX, and A <em>Nice</em> Markdown Document for HTML output.

Journal articles

Customize Word templates

Part II: New output formats

What is an output format?

Take html_document() for example:

str(rmarkdown::html_document(), 2)
List of 10
 $ knitr                  :List of 5
  ..$ opts_knit    : NULL
  ..$ opts_chunk   :List of 5
  ..$ knit_hooks   : NULL
  ..$ opts_hooks   : NULL
  ..$ opts_template: NULL
 $ pandoc                 :List of 6
  ..$ to          : chr "html"
  ..$ from        : chr "markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash"
  ..$ args        : chr [1:8] "--smart" "--email-obfuscation" "none" "--self-contained" ...
  ..$ keep_tex    : logi FALSE
  ..$ latex_engine: chr "pdflatex"
  ..$ ext         : NULL
 $ keep_md                : logi FALSE
 $ clean_supporting       : logi TRUE
 $ pre_knit               :function (...)  
 $ post_knit              :function (...)  
 $ pre_processor          :function (...)  
 $ intermediates_generator:function (original_input, encoding, intermediates_dir)  
 $ post_processor         :function (metadata, input_file, output_file, clean, verbose)  
 $ on_exit                :function ()  
 - attr(*, "class")= chr "rmarkdown_output_format"

It is a list of knitr and Pandoc options, plus some functions (pre/post processors). This list is typically generated by rmarkdown::output_format(). Type rmarkdown::html_document or rmarkdown::pdf_document in the R console, and take a look at the last few lines of the source code.

Examples of new output formats


Part III: Other applications

Build websites

Interactive Shiny documents

HTML widgets


  name: "FOO",

  type: "output",

  initialize: function(el, width, height) {
    // initialize the element

  renderValue: function(el, data, instance) {
    // render the data in el, e.g.
    // $(el).DataTable(data.options);


Run code from other languages in R Markdown