altdown
Links
License
Community
Citation
Developers
Bjarke Hautop Kristensen
Author, maintainer
Dev status
altdown is an R package that provides a theme for altdoc websites built with Quarto, styled to mirror the output of pkgdown (Bootstrap 5).
Installation
Install from GitHub:
pak::pak("https://github.com/BjarkeHautop/altdown")Usage
Browse around to see how it looks! If you like what you see, and want to use it for your own package, run:
altdown::use_altdown()This writes altdoc/altdown.yml, with a reference: field that lists your package’s current functions in one section; edit it to group them however you’d like, in the same shape as pkgdown’s reference: field. It also gitignores the files the build generates.
Then build the site:
altdown::build_site()A preview can then be viewed using altdoc::preview_docs().
The navbar is built from your vignettes: the one named after the package (or the only top-level one) becomes “Get started”, and the rest, including those in vignettes/articles/, go under “Articles”. If reftip is installed, build_site() also adds hover tooltips to references to your package’s functions. See ?altdown::build_site for everything altdown.yml can configure.
See also
reftip adds hover tooltips to the function reference links that altdoc creates in a rendered R code block; build_site() runs it automatically when it’s installed. alttip shows an example site using altdown and reftip together.
Why?
pkgdown supports Quarto (see vignette("quarto")), but the way it’s implemented is hard to maintain and lags behind in features. For instance, callout blocks, code annotations, and tabsets don’t work correctly. Callout blocks are what I personally wanted most, since I’ve grown fond of them.
This happens because pkgdown hardcodes theme: "none" and minimal: TRUE so it can supply its own CSS instead of Quarto’s, which strips the callout, annotation, and tabset styling. Callouts, for instance, get converted to plain blockquotes.
The fix would be patching pkgdown itself, but it’s a bit more involved than one would first think. The tldr is you have to merge two competing asset systems, which is not trivial. Hence I use altdoc, and manually construct my layout for something that looks like pkgdown.