Ideas for supporting Quarto in the Carpentries workbench

[milanmlft]

This is a brain dump of my current ideas, for anyone (including future me) who might pick this up.

Goal of this repo

carpentries-quarto would replace {varnish} to handle layout and formatting of carpentries lessons, so instead of a {pkgdown} template (which is what {varnish} currently defines), we would have a quarto extension that defines the styling of a carpentries lesson.

Ideally, this extension should be completely decoupled from {sandpaper} and it should be possible to use it independently. At the same time, a lesson developer using the Carpentries workbench shouldn't even be aware of the existence of this Quarto extension. {sandpaper} would handle the rendering of the lesson source material through {quarto}, and use this extension to define the output format.

{sandpaper} integration

The integration into {sandpaper} would happen by wrapping the {quarto-r} package in {sandpaper} to handle the setup and configuration of a lesson and then render the source *.[R,q]md|*.ipynb|... files to html, instead of using the knitr engine through {pkgdown} (unless {pkgdown} gets full support for Quarto, see note below). The carpentries-quarto extension would be added to the lesson repo as a local dependency during setup with regular checks to keep it up-to-date.

Note: there is quarto::quarto_add_extension() in the {quarto} R package which can be used to install the extension initially. Quarto extensions are installed by adding them to a local _extensions/ subdirectory of the project, so they would still have to be kept up-to-date. There is a quarto update CLI command but it doesn't seem to be present in the R package yet. For the automated builds on GitHub actions, I imagine that the extension will get re-installed for each workflow run, so that will use the latest version by default.

The package cache would still be handled by {sandpaper} as it is now, with support for Python added if #448 ever gets merged in
Note that Quarto also recommends {renv} when combining R and Python within the same project

Note

It looks like {pkgdown} will have (limited) support for Quarto in the near future, so it might be possible to retain the {pkgdown} wrapping functionality of {sandpaper} after all. This would make the transition much easier. Would have to look into more detail on how that integration would work though and whether it's compatible with the carpentries-quarto extension. See also r-lib/pkgdown#2656

In general, I'd say that the smaller we can make {sandpaper}, the better as it will be easier to maintain. If we use the infrastructure provided by stable, well-maintained projects such as quarto and {pkgdown}, less time will have to be spent on fixing and improving the general infrastructure and more time and energy can be spent on Carpentries-specific features.

Resources

• Can We use Quarto Yet? discussion on carpentries/sandpaper
• Quarto Extensions documentation
• quarto-dev/quarto-r: R interface to quarto-cli
• Good example of Quarto plugin with lots of Lua: https://github.com/coatless/quarto-webr
• pkgdown support for Quarto: Quarto articles? · Issue #2210 · r-lib/pkgdown
• Olivine-Labs/lustache: Mustache templates for Lua; which is what I used to to handle the mustache templates from {sandpaper}
• @zkamvar's ISC proposal for Quarto support