R Packages, 2nd Edition

Chapter 17. Vignettes

A vignette is a long-form guide to your package. Function documentation is great if you know the name of the function you need, but it’s useless otherwise. In contrast, a vignette can be framed around a target problem that your package is designed to solve. The vignette format is perfect for showing a workflow that solves that particular problem, start to finish. Vignettes afford you different opportunities than help topics: you have much more control over the integration of code and prose, and it’s a better setting for showing how multiple functions work together.

Many existing packages have vignettes, and you can see all the vignettes associated with your installed packages with browseVignettes(). To limit that to a particular package, you can specify the package’s name like so: browseVignettes("tidyr"). You can read a specific vignette with the vignette() function, e.g., vignette("rectangle", package = "tidyr"). To see vignettes for a package that you haven’t installed, look at the “Vignettes” listing on its CRAN page.

However, we much prefer to discover and read vignettes from a package’s website, which is the topic of Chapter 19.¹ Compare the vignette experience of tidyr’s CRAN page to what it feels like to access tidyr’s vignettes from its website. Note that pkgdown uses the term “article,” which feels like the right vocabulary for package users. The technical distinction between a vignette (which ships with a package) and an article (which is available ...