{{< include include/_intro.qmd >}}
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
andminimal: true
) - A custom CSS file is provided.
This is equivalent to
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.
- Added to
.Rbuildignore
(e.gusethis::use_build_ignore("vignettes/*_files")
) - Added to
.gitignore
(e.g.usethis::use_git_ignore("*_files", "vignettes")
)