+
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.
+
+- Added to
.Rbuildignore (e.g
+usethis::use_build_ignore("vignettes/*_files"))
+- Added to
.gitignore
+(e.g. usethis::use_git_ignore("*_files", "vignettes"))
+
+