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:

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 override by YAML header in the vignette source file. Only new configuration can be set, e.g adding a Table Of Content:

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

This is one limitation of the current implementation of the vignette engine. This is to insure HTML vignette produced are reasonable in size and can be published on CRAN without problem.

The other 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 default HTML format from Quarto and not the vignette engine one. Only building the vignette will produce the real results. More about building vignette 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.