License

Full license

MIT + file LICENSE

Community

Contributing guide

Citation

Citing altdown

Developers

Bjarke Hautop Kristensen
Author, maintainer

Dev status

altdown

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 copies altdoc/build-site.R, altdoc/altdown.scss, and altdoc/quarto_website_static.yml into your package as-is, and writes a starter altdoc/reference.yml listing your package’s current functions in one section. From there:

  • Edit reference.yml to group the functions however you’d like.

Then build the site:

source("altdoc/build-site.R")
build_site()

A preview can then be viewed using altdoc::preview_docs().

Re-run altdown::use_altdown(overwrite = TRUE) later to pick up altdown updates to the three template files.

See also

reftip adds hover tooltips to the function reference links that altdoc creates in a rendered R code block. 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.