Skip to contents

quartofix

pkgdown renders Quarto (.qmd) files with theme: "none" and minimal: TRUE so it can supply its own CSS instead of Quarto’s (documented here). Thus, currently the following is broken (silently!) when using .qmd files:

  • Callouts blocks gets converted to a plain, untyped blockquote.
  • Tabsets get actively mangled.
  • Code annotations keep their HTML/classes but lose the JS that makes them interactive.

quartofix fixes these. Two approaches are implemented:

  • quartofix(): Rewrites the broken things into Quarto’s native callout markup, and links in a small vendored CSS/JS bundle so tabsets and code annotations work without pulling in Quarto’s full asset bundle.

  • quartofix2(): Runs quarto render on the .qmd files with any callout blocks or tabsets. Code annotations are handled the same way as in quartofix(), since their markup already survives pkgdown’s render intact, only the vendored JS/CSS bundle needs to be linked in. Then patches it together with the generated .html from pkgdown.

    • TODO:
      • Could move callouts and tabsets (that don’t run the code (since it might need previous code)) into a seperate temp .qmd file. The cost of rendering this would be essentially 0, so potentially a decent speedup.

Installation

Install from GitHub:

pak::pak("https://github.com/bjarkehautop/quartofix")

Usage

Simply just call it after you build your site with pkgdown:

pkgdown::build_site()
quartofix::quartofix() # or quartofix2()

See the same demo article as raw pkgdown output, patched with quartofix(), and patched with quartofix2().

Background

I first started the other way around to get my Quarto features fully supported: Patch an altdoc site (which supports Quarto websites natively) to look like a pkgdown site, see altdown. Using altdown on an altdoc site should make it look very similar to a pkgdown site, but it was honestly harder and required more code than I first thought.

After learning from that, I took what I learned and tried to make it work the other way, hence I made this package.

I’ll probably make a PR upstream on pkgdown soon, but for now you can use this package. (Maybe only for the callout blocks and tabsets, since the fix for code annotations is more brittle and involved.)