Write Vignette

Write Vignette

Create long-form documentation vignettes for R packages.

When Use

• Adding "Getting Started" tutorial for package
• Documenting complex workflows that span multiple functions
• Creating domain-specific guides (e.g., statistical methodology)
• CRAN submission needs user-facing documentation beyond function help

Inputs

• Required: R package with functions to document
• Required: Vignette title and topic
• Optional: Format (R Markdown or Quarto, default: R Markdown)
• Optional: Whether vignette needs external data or APIs

Steps

Step 1: Create Vignette File

usethis::use_vignette("getting-started", title = "Getting Started with packagename")

Got: vignettes/getting-started.Rmd created with YAML frontmatter. knitr and rmarkdown added to DESCRIPTION Suggests field. vignettes/ directory exists.

If err: usethis::use_vignette() fails? Verify working directory is package root (contains DESCRIPTION). knitr not installed? Run install.packages("knitr") first. For manual creation, create vignettes/ directory and file by hand. Ensure YAML frontmatter includes all three %\Vignette* entries.

Step 2: Write Vignette Content

---
title: "Getting Started with packagename"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with packagename}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

Brief overview of what the package does and who it's for.

## Installation

```r
install.packages("packagename")
library(packagename)
```

## Basic Usage

Walk through the primary workflow:

```r
# Load example data
data <- example_data()

# Process
result <- main_function(data, option = "default")

# Inspect
summary(result)
```

## Advanced Features

Cover optional or advanced functionality.

## Conclusion

Summarize and point to other vignettes or resources.

Got: Vignette Rmd file contains Introduction, Installation, Basic Usage, Advanced Features, Conclusion sections. Code examples use package's exported functions and produce visible output.

If err: Examples fail to run? Verify package installed with devtools::install(). Ensure examples use package name in library() calls (not devtools::load_all()). For functions requiring external resources, use eval=FALSE to show code without execution.

Step 3: Configure Code Chunks

Use chunk options for different purposes:

# Standard evaluated chunk
{r example-basic}
result <- compute_something(1:10)
result

# Show code but don't run (for illustrative purposes)
{r api-example, eval=FALSE}
connect_to_api(key = "your_key_here")

# Run but hide code (show only output)
{r hidden-setup, echo=FALSE}
library(packagename)

# Set global options
{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)

Got: Setup chunk with include=FALSE sets global options (collapse, comment, fig.width, fig.height). Chunks configured appropriate: eval=FALSE for illustrative code, echo=FALSE for hidden setup, standard chunks for interactive examples.

If err: Chunk options not taking effect? Verify syntax uses {r chunk-name, option=value} format (comma-separated, no quotes around logical values). Check setup chunk runs first by placing at top of document.

Step 4: Handle External Dependencies

For vignettes that need network access or optional packages:

{r check-available, include=FALSE}
has_suggested <- requireNamespace("optionalpkg", quietly = TRUE)

{r use-suggested, eval=has_suggested}
optionalpkg::special_function()

For long-running computations, pre-compute and save results:

# Save pre-computed results to vignettes/
saveRDS(expensive_result, "vignettes/precomputed.rds")

# Load in vignette
{r load-precomputed}
result <- readRDS("precomputed.rds")

Got: External dependencies handled gracefully — optional packages conditionally loaded with requireNamespace(), network-dependent code uses eval=FALSE or tryCatch(), expensive computations use pre-computed .rds files.

If err: Vignette fails on CRAN due to unavailable optional packages? Wrap those sections with conditional variable (e.g., eval=has_suggested). For pre-computed results, ensure .rds file included in vignettes/ directory and referenced with relative path.

Step 5: Build and Test Vignette

# Build single vignette
devtools::build_vignettes()

# Build and check (catches vignette issues)
devtools::check()

Got: Vignette builds without errors. HTML output readable.

If err:

• Missing pandoc: Set RSTUDIO_PANDOC in .Renviron
• Package not installed: Run devtools::install() first
• Missing Suggests: Install packages listed in DESCRIPTION Suggests

Step 6: Verify in Package Check

devtools::check()

Vignette-related checks: builds correctly, doesn't take too long, no errors.

Got: devtools::check() passes with no vignette-related errors or warnings. Vignette builds within CRAN time limits (typically under 60 seconds).

If err: Vignette causes check failures? Common fixes: add missing Suggests packages to DESCRIPTION, reduce build time with eval=FALSE on slow chunks, ensure VignetteIndexEntry matches title. Run devtools::build_vignettes() separately to isolate vignette-specific errors.

Check

• Vignette builds without errors via devtools::build_vignettes()
• All code chunks execute correctly
• VignetteIndexEntry matches title
• devtools::check() passes with no vignette warnings
• Vignette appears in pkgdown site articles (if applicable)
• Build time reasonable (< 60 seconds for CRAN)

Pitfalls

• VignetteIndexEntry mismatch: Index entry in YAML must match what you want users to see in vignette(package = "pkg")
• Missing vignette YAML block: All three %\Vignette* lines required
• Vignette too slow for CRAN: Pre-compute results or use eval=FALSE for expensive operations
• Pandoc not found: Ensure RSTUDIO_PANDOC environment variable set
• Self-referencing package: Use library(packagename) not devtools::load_all() in vignettes

See Also

• write-roxygen-docs - function-level docs complement vignette tutorials
• build-pkgdown-site - vignettes appear as articles on pkgdown site
• submit-to-cran - CRAN has specific vignette requirements
• create-quarto-report - Quarto as alternative to R Markdown vignettes