pkgdown is the default way to build a documentation site for an R package, and it’s a great tool. But the support for Quarto is lacking. It does support .qmd vignettes (see vignette("quarto")), but the way it’s implemented is hard to maintain and lags behind in features. In practice this means things like callout blocks get flattened into plain blockquotes. I wanted callout blocks, since I’ve grown quite fond of them (maybe too much?), so I looked into alternatives.
The main alternative is altdoc, which takes an alternative approach and supports quarto websites natively. Great, I can use callout blocks now!
However, I quite liked the default look of pkgdown, (and additionally, altdoc doesn’t currently doesn’t support custom references page, see #326) so I wanted to replicate that look in altdoc. So I made altdown:
altdown: a pkgdown-styled altdoc site
altdown (site) is a package that adds a theme to mimic the look of Bootstrap 5 pkgdown, while still keeping the nice features a native Quarto website supports, via altdoc.
It’s called “altdown” because it’s an alternative to pkgdown, built on altdoc.
To reuse it for your own package, run altdown::use_altdown() from the package root. It copies the altdoc/ template in and writes a starter reference.yml from your existing man/*.Rd files. Then adjust the navbar links/vignettes in quarto_website_static.yml, group reference.yml the way you want, and run:
source("altdoc/build-site.R")
build_site()Great, now I can use callout blocks for my documentation sites, and otherwise it still looks like pkgdown!
Recently DocumenterCodeBlocks.jl was added to the Julia documentation ecosystem, adding hover previews and links to function documentation. This is quite nice, and I wanted the same features for my altdoc sites. So I made reftip:
reftip: preview on hover
altdoc’s quarto_website backend already turns function names in R code chunks into links, via Quarto’s code-link and the downlit package. But downlit only links to a published package, so it can’t resolve a local dev version of a package, an unpublished package, or a S3 method name like print.animal().
reftip (demo) is a small post-processing step that fixes that, and adds hover on preview, inspired by DocumenterCodeBlocks.jl. To use it simply just call reftip::add_tooltips() after you render docs:
altdoc::render_docs()
reftip::add_tooltips()Anything it can’t resolve to one of the package’s own topics, such as base R or another package is left exactly as Quarto/downlit rendered it.
- A generic call like
print(x)can’t be resolved, since that needs knowingx’s class at runtime, and reftip only readsman/*.Rd. - Same reason
obj$method()(R6) isn’t resolved. - An Rd page documenting several aliases under one
\usage{}block (an S3 generic plus its methods) shows the whole block in the tooltip, not just the line for the one alias that was linked.
It’s also currently only implemented for the quarto_website backend specifically; altdoc’s other three (mkdocs, docsify, docute) haven’t been tried (it might work/it might not).
If you are interested to see how the two packages work together I made alttip (site), which is just a toy package that uses them both.
Please let me know what you think!
Again I got inspired by DocumenterCodeBlocks.jl, which injects functions doing the website build for showcase, that aren’t actually exported. Both packages have a build_site() function, which doing build adds some toy functions, installs the package with these toy functions, and then renders the site.