Quarto HTML Vignettes

This is an example Quarto vignette, demonstrating how the quarto package can let you write R package vignettes with Quarto (https://quarto.org).

Quarto as vignette builder

Add this to your DESCRIPTION file:

VignetteBuilder:
    quarto

HTML Vignette Engines

The quarto R package registers vignette engines that can be used in %\VignetteEngine{} directives in vignette headers.

To learn more about how vignettes engine works, and how to write vignette engines, see the Writing R Extensions manual and the R Packages (2e) book.

To produce a HTML vignette engine, add this to your YAML header

vignette: >
  %\VignetteIndexEntry{Vignette's Title}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

This will build a HTML document using Quarto, suitable for using as vignette to publish on CRAN. Choice has been made to create a very minimal HTML vignette by default, and so it is built with the following changes based to Quarto’s format: html defaults:

• The HTML file produced is standalone (i.e. embed-resources: true)
• Bootstrap has been disabled (i.e. theme: none and minimal: true)
• A custom CSS file is provided.

This is equivalent to

format: 
  html:
    theme: none
    minimal: true
    embed-resources: true
    css: custom.css

All those configurations are set in way that they can’t be overriden by the YAML header in the vignette source file and only new configurations can be set. Typical examples for such configurations are adding a table of contents or enabling the rendering of mathematical notation in the format options, e.g., by MathJax. Specifically, these two options can be set in the following way:

format: 
  html:
    toc: true
    html-math-method: mathjax
vignette: >
  %\VignetteIndexEntry{Vignette's Title}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}

The minimal default format is a deliberate limitation of the current implementation of the vignette engine. It ensures that the HTML vignettes produced are reasonable in size and can be published on CRAN without problems.

Another limitation concerns the interactive rendering. If you render your vignette .qmd file using quarto render or any other function, the output will be based on the default HTML format from Quarto and not the vignette engine one. Only building the vignette will produce the real results. More details about building vignettes are available in the R Packages (2e) book.

Intermediates resources that would be created by an authoring workflow that would quarto render with default format: html should be ignored in package sources.

• Added to .Rbuildignore (e.g usethis::use_build_ignore("vignettes/*_files"))
• Added to .gitignore (e.g. usethis::use_git_ignore("*_files", "vignettes"))