16.8 R Markdown templates in R packages

Figure 16.4 of Section 16.7 illustrates the process of retrieving the editable Package Vignette (HTML) template from the rmarkdown package. This R Markdown file is pre-populated with the appropriate metadata for an R package vignette.

Similarly, any package may include R Markdown templates that package users can access through the RStudio IDE (as shown in the figure) or across any platform with the rmarkdown::draft() function.

16.8.1 Template use-cases

Templates are a useful way to share custom structure, style, and content. There are many excellent examples of this “in the wild.”

Many templates add structure and style by pre-populating the YAML metadata. We already saw an example of this with the rmarkdown package’s Package Vignette (HTML) template. Similarly, the rmdformats package (Barnier 2020) provides a number of templates that pass different custom styling functions to the output option.

Other templates demonstrate document structures that the packages require. For example, the pagedown package (Xie et al. 2020) includes numerous templates for posters, resumes, and other page layouts. Similarly, the xaringan package’s Ninja Presentation template (Xie 2020f) demonstrates the syntax for many different slide formatting options.

Templates may also demonstrate package features and syntax. For example, both the flexdashboard package (Iannone, Allaire, and Borges 2020) and the learnr package (Schloerke, Allaire, and Borges 2020) include templates with code chunks that call functions from the packages to create a sample dashboard or tutorial, respectively.

Similarly, templates may also include boilerplate content. For example, the rticles package (Allaire, Xie, R Foundation, et al. 2020) provides many such templates to align R Markdown output to the required style and content guidelines of different academic journals. Boilerplate content is also useful in organizational settings, such as a team generating quarterly reports.

16.8.2 Template setup

The usethis package (Wickham and Bryan 2020) has a helpful function for creating templates. Running usethis::use_rmarkdown_template("Template Name") will automatically create the required directory structure and files (you should provide your own Template Name).

If you wish to set up your template manually instead, create a subdirectory of the inst/rmarkdown/templates directory. Within this directory, you need to save at least two files:

  1. A file named template.yaml, which gives the RStudio IDE basic metadata such as a human-readable name for the template. At a minimum, this file should have the name and description fields, e.g.,

    1. name: Example Template
    2. description: What this template does

    You may include create_dir: true if you want a new directory to be created when the template is selected. This is useful if your template relies upon additional resources. For example, the learnr package template sets create_dir: true, whereas the flexdashboard package template uses the default create_dir: false. You may attempt to open both of these templates in RStudio to notice the different user prompts.

  2. An R Markdown document saved under skeleton/skeleton.Rmd. This may contain anything you wish to put in an R Markdown document.

Optionally, the skeleton folder may also include additional resources like style sheets or images used by your template. These files will be loaded to the user’s computer along with the template.

For more details on building custom R Markdown templates, please refer to the RStudio Extensions website and the Document Templates chapter of the R Markdown Definitive Guide (Xie, Allaire, and Grolemund 2018).

References

Allaire, JJ, Yihui Xie, R Foundation, Hadley Wickham, Journal of Statistical Software, Ramnath Vaidyanathan, Association for Computing Machinery, et al. 2020. Rticles: Article Formats for r Markdown. https://github.com/rstudio/rticles.

Barnier, Julien. 2020. Rmdformats: HTML Output Formats and Templates for Rmarkdown Documents. https://github.com/juba/rmdformats.

Iannone, Richard, JJ Allaire, and Barbara Borges. 2020. Flexdashboard: R Markdown Format for Flexible Dashboards. http://rmarkdown.rstudio.com/flexdashboard.

Schloerke, Barret, JJ Allaire, and Barbara Borges. 2020. Learnr: Interactive Tutorials for r. https://CRAN.R-project.org/package=learnr.

Wickham, Hadley, and Jennifer Bryan. 2020. Usethis: Automate Package and Project Setup. https://CRAN.R-project.org/package=usethis.

———. 2020f. Xaringan: Presentation Ninja. https://github.com/yihui/xaringan.

Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.

Xie, Yihui, Romain Lesur, Brent Thorne, and Xianying Tan. 2020. Pagedown: Paginate the HTML Output of r Markdown with CSS for Print. https://github.com/rstudio/pagedown.