These are some random notes from a two hour advanced RMarkdown tutorial given by Yihui Xie on January 14, 2017 at the first RStudio conference (slides).

# Initialize
library(dplyr)
library(knitr)
opts_chunk$set(message=FALSE, warning=FALSE)

RMarkdown Extensions

rticles

The rticles package has \(\LaTeX\) Journal Article Templates for R Markdown for various journals, including JSS, the R Journal, ACM, ACS, AMS, Elsevier journals, etc. After doing this you can initialize a new PDF document from a template.

tufte

The tufte package now supports both PDF and HTML output. See an example here: http://rstudio.github.io/tufte/. Install from CRAN and put this in your YAML header:

---
title: "An Example Using the Tufte Style"
author: "John Smith"
output:
  tufte::tufte_handout: default
  tufte::tufte_html: default
---

xaringan

Yihui’s xaringan package ports the remark.js library for slideshows into R. Careful. Yihui warns that you may not sleep after learning about how cool remark.js is. More resources:

bookdown

The bookdown package is just awesome. Takes multiple RMarkdown documents and renders into multiple output formats (screen-readable ebook, PDF, epub, etc.). Great for writing books and technical documentation with pushbutton publishing to multiple output formats. Has nice built-in styles. Some examples:

Also see RStudio’s webinar on bookdown, and see examples and the “Getting Started” link at bookdown.org.

Output formats

Customizing

Output formats are lists of various options. For example, see the str() of the return value of the HTML document.

str(rmarkdown::html_document())
## List of 11
##  $ knitr                  :List of 5
##   ..$ opts_knit    : NULL
##   ..$ opts_chunk   :List of 5
##   .. ..$ dev       : chr "png"
##   .. ..$ dpi       : num 96
##   .. ..$ fig.width : num 7
##   .. ..$ fig.height: num 5
##   .. ..$ fig.retina: num 2
##   ..$ 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:11] "--smart" "--email-obfuscation" "none" "--self-contained" ...
##   ..$ keep_tex    : logi FALSE
##   ..$ latex_engine: chr "pdflatex"
##   ..$ ext         : NULL
##  $ keep_md                : logi FALSE
##  $ clean_supporting       : logi TRUE
##  $ df_print               : chr "default"
##  $ 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"

By default uses the bootstrap theme. Straightforward to modify. If you don’t like, simply set to NULL if you don’t want a theme.

output: 
  html_document:
    toc: TRUE
    theme: NULL

You could also use any of the other build-in bootstrap themes: default, cerulean, journal, flatly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, or yeti.

Random Tips

  • pandoc::render(clean=FALSE) will not remove intermediate files. Useful for debugging because you can now run the render command in the console.
  • YAML metadata values are translated into arguments in the render(...) function.
  • You can also use includes: YAML option, with sub-options in_header, before_body, and after_body to specify arbitrary HTML code injected into the respective output. You can similarly do this with \(\LaTeX\) using includes with sub-option in_header specifying a .tex file.