Technical details

Source: vignettes/articles/technical.qmd

quartodown generates a Quarto website project from the package sources, so the man pages, vignettes and generated pages are all Quarto pages, and every Quarto feature works.

How a build works

quartodown::build_site() runs in three stages:

Before rendering, it installs the package into a temporary library, writes a Quarto project into _quarto/ and runs the reference pages’ examples against that package.
During rendering, Quarto renders _quarto/ into docs/, running the vignettes against that package.
After rendering, it links code to its documentation, adds hover tooltips, puts the logo by each page’s title and writes the redirect pages.

With development: mode: devel, the site goes in docs/dev/ instead, and a build into docs/ leaves dev/ as it is.

In an interactive session it then serves the site with preview_site(). The server keeps running for the rest of the session, so after a rebuild the open page reloads instead of a new one opening.

build_site(devel = TRUE) skips the install and loads the package from source with pkgload::load_all() instead. It is faster, but code that starts other R processes (for example with callr or parallel) won’t find the package, and build-stage \Sexpr{} macros in the man pages don’t run.

build_site()’s workers argument sets the number of processes to build with. More than one needs the mirai package.

build_site(freeze = TRUE) reuses the results of code from an earlier build, kept in _quarto/_freeze/, for pages whose source hasn’t changed (Quarto’s freeze). Committing _quarto/_freeze/ lets builds on CI reuse them too.

Warning

Freeze only checks each page’s own source, not your package’s code or the packages it uses. After changing a function or updating a dependency, the pages running that code keep their old output until you delete _quarto/_freeze/.

Throughout the build, the environment variable IN_QUARTODOWN is "true", so the package’s code can tell it is running for the site, and IN_QUARTODOWN_PKG is the package’s name.

_quarto/ is rewritten on every build, and gitignored by quartodown::use_quartodown(). To change the site, edit _quartodown/ instead (see Customizing your site).

_quarto/
├── _quarto.yml                   # Quarto configuration (navbar, footer, theme)
├── index.qmd                     # home page
├── reference/
│   ├── index.qmd                 # function reference index
│   └── <topic>.qmd               # a page per man/*.Rd
├── authors.qmd                   # authors and citation page
├── vignettes/                    # the vignettes, as they are
├── man/figures/                  # images for the README and man pages
├── NEWS.md                       # changelog, titled, with issues and users linked
├── _quartodown/                  # the package's _quartodown/, as it is
└── quartodown.scss               # theme on top of Quarto's HTML

The files listed under vignettes: files: (see Customizing your site) are copied to the same paths, so that the vignettes’ relative paths to them resolve as in the package. Documents in them aren’t rendered as pages.

The man pages

Each man/*.Rd file becomes a reference page, served at reference/<topic>.html. It is rendered with the package’s Rd macros (such as Rdpack’s \insertRef{}), and build-stage \Sexpr{} macros run with the package installed, as in R CMD build. Examples run, with their output in the same block as the code, prefixed with #>. To give a chunk’s output a block of its own, in a vignette too, set #| collapse: false on it.

To save Quarto starting an R process per page, all examples run beforehand in one R process, which resets the global environment, search path, options and the like between pages, as R CMD check does. Pages whose examples fail or produce HTML widgets are left for Quarto to run.

Under its title, each reference page and vignette links to its source file in the package’s repository, if it has one.

Code links and tooltips

downlit links function calls in R code blocks, and inline code like mean(), to their documentation. docs/pkgdown.yml lets downlit on other sites link to your reference pages in turn.

That file needs the site’s address: url: in _quartodown/_quartodown.yml, or else the first URL in DESCRIPTION that isn’t a GitHub, GitLab or Codeberg repository.

References to the package’s own functions also get a hover tooltip with their usage and the first sentence of their description. build_site() warns when a first sentence is longer than 200 characters, since the tooltip cuts it off. To build without tooltips, use build_site(tooltips = FALSE).

The theme

The site has a light and a dark theme, and follows the browser’s preference. Each is built in layers:

the Quarto theme: default in light mode and darkly in dark mode, unless theme: picks others,
quartodown.scss, quartodown’s own styling,
_quartodown/extra.scss, if the package has one.

With the default light theme, quartodown-fonts.scss also gives the dark theme the same system fonts and heading sizes.

Code output keeps the colors packages such as cli give it in a terminal, in shades that suit the light or dark theme.