Build an altdown-themed altdoc website

Description

Builds the package website into docs/ with altdoc::render_docs(), styled to mirror pkgdown. Before rendering it generates, from the package sources and altdoc/altdown.yml:

Usage

build_site(
  path = ".",
  tooltips = requireNamespace("reftip", quietly = TRUE),
  ...
)

Arguments

path Path to the package root.
tooltips Logical. Add hover tooltips to references to the package’s own functions with reftip::add_tooltips()? Defaults to TRUE when reftip is installed.
... Passed on to altdoc::render_docs(), e.g. freeze or parallel.

Details

  • the navbar, with a "Get started" link, the function reference, an "Articles" menu and the changelog;

  • the home page, built from README.md plus a pkgdown-style sidebar (links, license, citation, developers and the README’s badges);

  • the grouped function reference index;

  • the "Authors and Citation" page.

These generated files are written to altdoc/ (which altdoc copies into its Quarto project), so they’re gitignored by use_altdown(). README.md itself is never modified.

Value

Invisibly, the path to the built site.

Configuration

altdoc/altdown.yml (created by use_altdown()) can contain:

  • reference: groups the function reference index, in the same shape as pkgdown’s reference: field. contents entries can be a topic alias or a selector: starts_with(), ends_with(), contains(), matches(), has_concept(), has_keyword(), - to exclude, and c() to combine. Without it, every topic is listed in one section.

  • articles: the order of the "Articles" navbar menu, as vignette paths relative to vignettes/ without extension (e.g. articles/details). Without it, every vignette other than the "Get started" one is listed, top-level vignettes first, then those in vignettes/articles/.

  • quarto: settings merged (with utils::modifyList()) over the generated Quarto configuration, e.g. to add navbar entries or extra SCSS files.

The "Get started" link points to the vignette named after the package, or to the only top-level vignette if there is just one.