This is an example Quarto vignette, demonstrating how the quarto package can let you write R package vignettes with Quarto (https://quarto.org).
Add this to your DESCRIPTION
file:
VignetteBuilder:
quarto
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:
embed-resources: true
)theme: none
and minimal: true
)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.
.Rbuildignore
(e.g usethis::use_build_ignore("vignettes/*_files")
).gitignore
(e.g. usethis::use_git_ignore("*_files", "vignettes")
)