Quarto on Steroids: Advanced Customization through Quarto Extensions
Using and Contributing Quarto Extensions for Custom Formats.
I’ve said it before and I’ll say it again: Quarto is amazing! Since the beginning of my PhD I haven’t used any other tool for prototyping, writing and publishing any of my work.1 That work has included: this website, presentations, academic articles, notebooks and more. By highlighting useful features of Quarto in articles like this one, I hope to encourage more people to try it out.
While I’m convinced that Quarto can be useful in almost any context including industry, I realize that certain obstacles may have so far prevented some of you from using it. One such obstacle concerns custom formats: the standard Quarto formats for HTML, PDF, Revealjs, etc. are slick but minimalistic. For many formats, there are various themes to choose from, but they too lack personal touch (or corporate identity in the industry setting).
At first sight, traditional publishing tools like MS Office seem to have an edge here: customization is made easy through GUIs and standardization through templates is possible to a certain degree. I understand the appeal but still would encourage you to look beyond MS Word, Powerpoint and Beamer presentations. To this end, I’ve put together this short tutorial that explains how I have built and contributed a TU Delft theme for Revealjs. If nothing else, this theme can be used by my colleagues at Delft University of Technology to create beautiful, Delft-styled presentations with ease.
📖 Background
Advanced and reproducible customization in Quarto is done through Quarto Extensions:
“Quarto Extensions are a powerful way to modify or extend the behavior of Quarto, and can be created and distributed by anyone.”
— Quarto team
Users can already utilize several open-sourced extensions that add filters, journal article formats and other custom formats. As we will see, it is very straightforward to contribute extensions, so the list of available extensions is growing quickly.
🫴 Contributing Quarto Extensions
Normally, I would start by explaining how to use Quarto Extensions, but in this particular case the user and developer experience is so close that I’ll jump straight into development.
Setup
To get started with building the TU Delft Custom Format I followed the official Quarto docs. I first used the appropriate Quarto command, which initiates an interactive process in the command line:
Once done, the basic folder structure for my extension was set up and ready to be pushed to a remote Github repository for distribution: https://github.com/pat-alt/quarto-tudelft. Even though I had not yet added any custom formatting rules, anyone would now be able to use this empty extension for their work.
Adding Rules
To actually add some custom formatting rules to the extension I started working on the files contained in _extensions/tudelft/. Using my institution’s PowerPoint template as a reference, I previewed the template.qmd file and simply made appropriate adjustments to the _extensions/tudelft/custom.scss and _extensions/tudelft/_extension.yml files until I was satisfied. To help me in that process, I took inspiration from various existing Revealjs extensions all listed in the awesome-quarto repository.
I am no expert in CSS (far from it!), so this was very much trial-and-error based, but I got there eventually. One feature I am particularly happy about is the custom transition slides: by default all slides at level 1, so slides that initiate a new section,
will be formatted in a standardized way. The relevant CSS rule can be found here
Adding Assets
The Reavealjs template also includes a few images, which I have lifted from my institution’s PowerPoint template. To make sure that these images are also available locally when users install the template, any resources need to be stored inside the theme directory _extensions/tudelft/. I have had some issues pointing to the right location of these images in the _extensions/tudelft/custom.scss and _extensions/tudelft/_extension.yml file. At the time of writing this, the image URLs are pointing to their remote location on Github (see here). This works, but probably isn’t ideal, so any suggestions are welcome.
📋 Example Presentation - Using Quarto Extensions
In February, 2023, I will present a research paper on Algorithmic Recourse at the first IEEE Conference on Secure and Trustworthy Machine Learning: SaTML 2023. This was a good incentive for me to build a TU Delft Theme once for this occasion and then be able to reuse it again in the future.
With the template built and distributed, how do you actually use it?
This part is truly a walk in the park. As outlined in the README users can either work directly with the template,
or add the template to an existing Quarto project:
The first option will get you started with a working document straight away. For my paper presentation, I worked with the second option. At the time of writing, I am building and hosting all of my presentations in my website repository (the repo that also builds this very article you’re reading): https://github.com/pat-alt/pat-alt.github.io.
With the extension added to the project, I can now use it anywhere within that project by simply specifying,
in the YAML header of my Quarto document where tudelft-revealjs is just the name of the custom format.
It gets better … The extension can be extended further by providing yet another custom style sheet, as I have done for my paper presentation:
Check out the final presentation here or see the embedded version below:
Footnotes
Not entirely true: I’ve also used
Pluto.jl🎈 and had to resort to.Rmdin one particular case.↩︎
Citation
@online{altmeyer2023,
author = {Altmeyer, Patrick},
title = {Quarto on {Steroids:} {Advanced} {Customization} Through
{Quarto} {Extensions}},
date = {2023-01-16},
url = {https://www.paltmeyer.com/blog//blog/posts/quarto-extensions},
langid = {en}
}