Vignettes offer a lot of freedom in comparison to something like a help file.

They are typically written like an article, with an introduction, and multiple sections (notice the table on contents on the right!).

You can also include code chunks, code output, and visualizations.

A cornerstone of good vignettes are self-contained reproducible examples (reprex).

You can share the step-by-step of running your code, but also the logic of why you made it that way.

If users understand how you think about your package, it can help them solve their own problems, or maybe even contribute to the package themselves!

Most packages have a main introduction vignette that explains the broad purpose of the package.

However, it is also common to have multiple vignettes to explain different parts of the package in more depth.

Think about it like having maps at two different resolutions.

Vignettes live in the ./vignettes/ folder as .rmd files.

You can reference any of your functions or package data in the vignettes.

Importantly, it is one fo the few places you can use functions like library(), as it is meant to mimic user interaction with your package.

You can use usethis::use_vignette("NAME") to create the required directories and a template file.

Much like our the helpers, you will need to do the work of filling it out.

It is mostly a regular R markdown document, with some extra options in the YAML header.

Creates a .rmd file, not Quarto!

---
title: "THESE-MUST-MATCH"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{THESE-MUST-MATCH}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

'''{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
'''

'''{r setup}
library(mypackage)
'''

You can use usethis::use_vignette("my-vignette") to create the required directories and a template file.

Much like our the helpers, you will need to do the work of filling it out.

It is mostly a regular R markdown document, with some extra options in the YAML header.

Creates a .rmd file, not Quarto!

---
title: "THESE-MUST-MATCH"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{THESE-MUST-MATCH}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

'''{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
'''

'''{r setup}
library(mypackage)
'''

You must render your vignette with the knit button.

However, be aware that the document will use the version of your package you currently have installed.

This means you will need to install your package again if you have made any major changes you want to see in the document.

You should only use packages that your package has an official dependency on.

Otherwise, you have no idea if the person installing your package will the the required packages installed.

Remember to add anything you need to your imports!

Topic

Package Website

To-Do

• Finish Worksheet
• READ: 20 Website
• FILL OUT: Student’s Choice Survey