Technical details

This page explains how the site is put together. It is a Quarto website built with altdoc, with some extra styling and JavaScript to make it look like a pkgdown (Bootstrap 5) site.

Here is an overview of the customization implemented:

altdoc/
├── build-site.R               # pre-processing script, see below
├── quarto_website_static.yml  # source of quarto_website.yml
├── quarto_website.yml         # generated - not edited directly
├── altdown.scss               # pkgdown-style theme on top of Quarto's HTML
├── reference.yml              # source of reference.qmd
└── reference.qmd              # generated - not edited directly

Why a pre-processing script?

For a Quarto backend, the intended approach is to modify the source files with a script and then call altdoc::render_docs() yourself (see altdoc’s customization vignette).

That is what is done in altdoc/build-site.R. It does three main things, explained in details below:

The home page

altdoc always uses README.md as the home page. The script reads it, makes the necessary changes, writes the modified version temporarily, and restores the original when it is done. If you use a README.qmd, the script renders it to README.md, via quarto::quarto_render(readme_qmd, output_format = "gfm").

These changes also add a .column-margin sidebar, matching pkgdown’s layout, and move badges into it automatically.

The reference index

altdoc does not currently have a _pkgdown.yml-style reference: field for controlling how the function index is grouped and ordered (etiennebacher/altdoc#326).

So this package has its own altdoc/reference.yml, using the same basic structure as pkgdown’s reference: field. The build script uses it together with the \name{} and \alias{} entries in man/*.Rd to generate altdoc/reference.qmd.

The footer

altdoc/quarto_website.yml is generated from altdoc/quarto_website_static.yml. As part of this, the build script replaces $ALTDOC_DEVELOPED_BY with the “Developed by .” text used by pkgdown, based on Authors@R.

Matching the pkgdown look

altdown.scss is a Quarto theme layer:

theme: [default, altdown.scss]

It is based on pkgdown’s own pkgdown.scss, but the selectors have been adapted to Quarto’s HTML.

It does the following:

• Limiting the navbar to a centered, fixed-width container.
• Putting the navbar items (title, links, search, GitHub icon) in the same order as pkgdown.
• Styling the margin sidebar and reference index (<dl class="ref-index">) to look like their pkgdown counterparts.

There is one annoying thing that can’t be fixed though: the navbar title does not line up with the body text automatically. Quarto uses a different layout for the home page, so the body’s left edge is not in the same place on every page. Therefor, the generated quarto_website.yml includes a small include-after-body script that measures the actual offset after the page has loaded and adjusts the navbar padding accordingly.