3.8 R package vignette

The html_vignette format provides a lightweight alternative to html_document suitable for inclusion in packages to be released to CRAN. It reduces the size of a basic vignette from 600Kb to around 10Kb. The format differs from a conventional HTML document as follows:

  • Never uses retina figures
  • Has a smaller default figure size
  • Uses a custom lightweight CSS stylesheet

To use html_vignette, you specify it as the output format and add some additional vignette related settings via the \Vignette*{} macros:

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

Note that you should change the title field and the \VignetteIndexEntry{} to match the title of your vignette.

Most options for html_document (Section 3.1) also work for html_vignette, except fig_retina and theme, which have been set to null internally in this format.

The html_vignette template includes a basic CSS theme. To override this theme, you can specify your own CSS in the document metadata as follows:

output:
  rmarkdown::html_vignette:
    css: mystyles.css

The default figure size is 3x3. Because the figure width is small, usually you will be able to put two images side-by-side if you set the chunk option fig.show='hold', e.g.,

```{r, fig.show='hold'}
plot(1:10)
plot(10:1)
```

If you want larger figure sizes you can change the fig_width and fig_height in the document output options or alternatively override the default options on a per-chunk basis.