17.2 Workflow for writing a vignette

To create your first vignette, run:

usethis::use_vignette("my-vignette")

This does the following:

  • Creates a vignettes/ directory.

  • Adds the necessary dependencies to DESCRIPTION, i.e. adds knitr to the VignetteBuilder field and adds both knitr and rmarkdown to Suggests.

  • Drafts a vignette, vignettes/my-vignette.Rmd.

  • Adds some patterns to .gitignore to ensure that files created as a side effect of previewing your vignettes are kept out of source control (we’ll say more about this later).

This draft document has the the key elements of an R Markdown vignette and leaves you in a position to add your content. You also call use_vignette() to create your second and all subsequent vignettes; it will just skip any setup that’s already been done.

Once you have the draft vignette, the workflow is straightforward:

  • Start adding prose and code chunks to the vignette. Use devtools::load_all() as needed and use your usual interactive workflow for developing the code chunks.

  • Render the entire vignette periodically.

This requires some intention, because unlike tests, by default, a vignette is rendered using the currently installed version of your package, not with the current source package, thanks to the initial call to library(yourpackage).

One option is to properly install your current source package with devtools::install() or, in RStudio, Ctrl/Cmd + Shift + B. Then use your usual workflow for rendering an .Rmd file. For example, press Ctrl/Cmd + Shift + K or click .

Another option is to use devtools::build_rmd(“vignettes/my-vignette.Rmd”) to render the vignette. This builds your vignette against a (temporarily installed) development version of your package.

It’s very easy to overlook this issue and be puzzled when your vignette preview doesn’t seem to reflect recent developments in the package. Double check that you’re building against the current version!

  • Rinse and repeat until the vignette looks the way you want.