R Markdown Custom Formats
This article is originally published at https://www.rstudio.com/blog/
The R Markdown package ships with a raft of output formats including HTML, PDF, MS Word, R package vignettes, as well as Beamer and HTML5 presentations. This isn’t the entire universe of available formats though (far from it!). R Markdown formats are fully extensible and as a result there are several R packages that provide additional formats. In this post we wanted to highlight a few of these packages, including:
tufte — Documents in the style of Edward Tufte
rticles — Formats for creating LaTeX based journal articles
rmdformats — Formats for creating HTML documents
We’ll also discuss how to create your own custom formats as well as re-usable document templates for existing formats.
Using Custom Formats
Custom R Markdown formats are just R functions which return a definition of the format’s behavior. For example, here’s the metadata for a document that uses the html_document format:
---
title: "My Document"
output: html_document
---
When rendering, R Markdown calls the rmarkdown::html_document function to get the definition of the output format. A custom format works just the same way but is also qualified with the name of the package that contains it. For example, here’s the metadata for a document that uses the tufte_handout format:
---
title: "My Document"
output: tufte::tufte_handout
---
Custom formats also typically register a template that helps you get started with using them. If you are using RStudio you can easily create a new document based on a custom format via the New R Markdown dialog:
Tufte Handouts
The tufte package includes custom formats for creating documents in the style that Edward Tufte uses in his books and handouts. Tufte’s style is known for its extensive use of sidenotes, tight integration of graphics with text, and well-set typography. Formats for both LaTeX and HTML/CSS output are provided (these are in turn based on the work in tufte-latex and tufte-css). Here’s some example output from the LaTeX format:
If you want LaTeX/PDF output, you can use the tufte_handout format for handouts and tufte_book for books. For HTML output, you use the tufte_html format. For example:
---
title: "An Example Using the Tufte Style"
authors: "John Smith"
output:
tufte::tufte_handout: default
tufte::tufte_html: default
---
You can install the tufte package from CRAN as follows:
install.packages("tufte")
See the tufte package website for additional documentation on using the Tufte custom formats.
Journal Articles
The rticles package provides a suite of custom R Markdown LaTeX formats and templates for various journal article formats, including:
You can install the rticles package from CRAN as follows:
install.packages("rticles")
See the rticles repository for more details on using the formats included with the package. The source code of the rticles package is an excellent resource for learning how to create LaTeX based custom formats.
rmdformats Package
The rmdformats package from Julien Barnier includes three HTML based document formats that provide nice alternatives to the default html_document format that is included in the rmarkdown package. The readthedown format is inspired by the Read the docs Sphinx theme and is fully responsive, with collapsible navigation:
The html_docco and html_clean formats both provide provide automatic thumbnails for figures with lightbox display, and html_clean provides an automatic and dynamic table of contents:
You can install the rmdformats package from CRAN as follows:
install.packages("rmdformats")
See the rmdformats repository for documentation on using the readthedown, html_docco, and html_clean formats.
Creating New Formats
Hopefully checking out some of the custom formats described above has you inspired to create your very own new formats. The R Markdown website includes documentation on how to create a custom format. In addition, the source code of the tufte, rticles, and rmdformats packages provide good examples to work from.
Short of creating a brand new format, it’s also possible to create a re-usable document template that shows up within the RStudio New R Markdown dialog box. This would be appropriate if an existing template met your needs but you wanted to have an easy way to create documents with a pre-set list of options and skeletal content. See the article on document templates for additional details on how to do this.
Thanks for visiting r-craft.org
This article is originally published at https://www.rstudio.com/blog/
Please visit source website for post related comments.
