17.3 Metadata

The first few lines of the vignette contain important metadata. The default template contains the following information:

---
title: "Vignette Title"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

This metadata is written in YAML, a format designed to be both human and computer readable. YAML frontmatter is a common feature of RMarkdown files. The syntax is much like that of the DESCRIPTION file, where each line consists of a field name, a colon, then the value of the field. The one special YAML feature we’re using here is >. It indicates that the following lines of text are plain text and shouldn’t use any special YAML features.

The default vignette template uses these fields:

  • title: this is the title that appears in the vignette. If you change it, make sure to make the same change to VignetteIndexEntry{}. They should be the same, but unfortunately that’s not automatic.

  • output: this specifies the output format. There are many options that are useful for regular reports (including html, pdf, slideshows, etc.), but rmarkdown::html_vignette has been specifically designed for this exact purpose. See ?rmarkdown::html_vignette for more details.

  • vignette: this is a block of special metadata needed by R. Here, you can see the legacy of LaTeX vignettes: the metadata looks like LaTeX comments. The only entry you might need to modify is the . This is how the vignette appears in the vignette index and it should match the title. Leave the other two lines alone. They tell R to use knitr to process the file and that the file is encoded in UTF-8 (the only encoding you should ever use for a vignette).

We generally don’t use these fields, but you will see them in other packages:

author: we don’t use this unless the vignette is written by someone not already credited as a package author.

date: we think this usually does more harm than good, since it’s not clear what the date is meant to convey. Is it the last time the vignette source was updated? In that case you’ll have to manage it manually and it’s easy to forget to update it. If you manage date programmatically with Sys.date(), the date reflects when the vignette was built, i.e. when the package bundle was created, which has nothing to do with when the vignette or package was last modified. We’ve decided it’s best to omit the date.

The draft vignette also includes two R chunks. The first one configures our preferred way of displaying code output and looks like this:

The second chunk just attaches the package the vignette belongs to.

library(yourpackage)

We might be tempted to (temporarily) replace this library() call with load_all(), but they advise that we don’t. Instead, we can use the techniques given in Section 18.2 to exercise our vignette code with the current source package.