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 2022) 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. 2022) includes numerous templates for posters, resumes, and other page layouts. Similarly, the xaringan package’s Ninja Presentation template (Xie 2024d) demonstrates the syntax for many different slide formatting options.
Templates may also demonstrate package features and syntax. For example, both the flexdashboard package (Aden-Buie, Sievert, et al. 2023) and the learnr package (Aden-Buie, Schloerke, et al. 2023) 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, Dervieux, R Foundation, et al. 2024) 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, Bryan, et al. 2024) 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:
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 thenameanddescriptionfields, e.g.,name: Example Template description: What this template doesYou may include
create_dir: trueif 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 setscreate_dir: true, whereas the flexdashboard package template uses the defaultcreate_dir: false. You may attempt to open both of these templates in RStudio to notice the different user prompts.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).