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.

The only file a package keeps in altdoc/ is altdown.yml. Everything else there is written by altdown::build_site() on every build, and gitignored:

altdoc/
├── altdown.yml                # configuration, edited by hand
├── quarto_website.yml         # Quarto configuration (navbar, footer, theme)
├── index.md                   # home page
├── reference.qmd              # function reference index
├── authors.qmd                # authors and citation page
├── altdown.scss               # pkgdown-style theme on top of Quarto's HTML
├── altdown-header.html        # dark-mode default
├── altdown-after-body.html    # navbar alignment, see below
└── altdown-pre-render.R       # fixes up altdoc's man pages, see below

Why generate files?

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 build_site() does. altdoc copies altdoc/ into its Quarto project, so files written there before altdoc::render_docs() end up in the site. The main ones are explained below.

The home page

altdoc’s home page is an index.md that includes README.md. Since altdoc copies altdoc/ into its Quarto project after importing the README, build_site() writes its own altdoc/index.md to replace it: the README with a .column-margin sidebar, matching pkgdown’s layout, with the README’s badges moved into it. README.md itself is never modified.

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 altdoc/altdown.yml has a reference: field, using the same basic structure as pkgdown’s. build_site() uses it together with the \name{} and \alias{} entries in man/*.Rd to generate altdoc/reference.qmd.

The navbar and footer

altdoc/quarto_website.yml is generated in full: the navbar links the “Get started” vignette, the reference index, the other vignettes under “Articles” and the changelog, and the footer has the “Developed by .” text used by pkgdown, based on Authors@R. A quarto: field in altdown.yml is merged over it.

The man pages

altdoc converts each man/*.Rd file to a .qmd page during altdoc::render_docs(), and renders the Quarto project straight after, so build_site() can’t edit those pages beforehand. Instead altdown-pre-render.R runs as a Quarto pre-render script, inside that render. It turns the Usage section into a highlighted R code block, rewrites inline <code> as Markdown code spans (so Pandoc doesn’t turn their " into curly quotes), and turns examples that aren’t run (\dontrun{}) into plain code blocks, so those pages don’t need knitr and a separate R session each.

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. Therefore, 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.