Quarto
Swiss army knife for hand-whittling scientific reports, slides and blogs
April 30, 2022 — May 2, 2025
A new entrant to the world of scientific notebooks and academic blogging. Kind of a competitor/complement to Jupyter and blogdown, Quarto unites these other systems and shares some developers, tools, and workflows with those projects.
Quarto® is an open-source scientific and technical publishing system built on Pandoc
- Create dynamic content with Python, R, Julia, and Observable.
- Author documents as plain text markdown or Jupyter notebooks.
- Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.
- Author with scientific markdown, including equations, citations, cross-references, figure panels, callouts, advanced layouts, and more.
Notable claims:
Pandoc markdown has excellent support for LaTeX equations and citations. Quarto adds extensions for cross-references, figure panels, callouts, advanced page layouts, and more.
and
Engage readers by adding interactive data exploration to your documents using Jupyter Widgets, htmlwidgets for R, Observable JS, and Shiny.
So it does some of the same things that Jupyter and blogdown do, regarding diverse output, but attempts to tie them together into a single scientific workbook engine with consistent support for the fiddly bits.
It seems to load Jupyter notebook source docs just fine, and notably promises that it will actually render citations correctly in Jupyter, which is an upgrade.
C&C codebraid.
1 Vibes
Does enough of what I want that I use it, despite qualms. I can ignore most of the complexity involved in delivering what it delivers, because by default it mostly does close to what I want. It has an active, friendly developer community.
After nearly one year of full-time, daily Quarto use, I have feelings and thoughts about Quarto.
Quarto’s strong ecosystem is a vote in its favour. There are vibrant discussion boards, many active developers, many active users, and good integrations into various IDEs (VS Code, RStudio etc). It has a corporate sponsor, Posit FKA RStudio, who sell some extra add-ons, some of which I am a fan of (Shiny, Posit Connect).
I have said on-record that a vibrant community is a better test of usefulness and predictor of future support for some software than my feeble, biased personal, aesthetic judgement. But please, read on, if you nonetheless desire to know my aesthetic judgement.
2 Quarto Integrated Website System
This section got so big I broke it out into the post Quarto Integrated Website System. tl;dr: Quarto websites are easy to set up for content creators, but as they get larger, they become slow and bloated when the website gets big. Configuration from the opinionated default looks easy, but has many pitfalls in practice.
3 Websites via Hugo
Hugo is a supported backend for Quarto. This sounded like it might be an easy migration path for my blogdown, but it turns out I am not a huge fan of this approach; it breaks the tight integration with Pandoc which is IMO a major advantage of Quarto over blogdown. Blogdown works perfectly well as a Hugo frontend, so why migrate away from it if it does not gain us much?
Answer: Hugo is much faster than Quarto’s built-in system, so if you have a big site, it might be worth it. I have a faint sting of buyer’s remorse about that, but I did not notice until it was too late.
4 Websites via Docusaurus
Docusaurus is a static site generator for documentation sites. It is not as home-grown as the built-in one and has developers who really hate complexity. Maybe that means it is good? Quarto supports Docusaurus. Let me know if you have any luck with it.
5 Customisation
5.1 Build a custom format
If you dislike the current website (or journal article, or presentation…) system, you can make a whole new format that uses the Quarto backend.
Quarto format extensions enable you to add new formats to the built-in formats (e.g.
html,docx) already available. Custom formats can provide default document options, stylesheets, header, footer, or logo elements, and even bundle other extensions like filters and shortcodes. They are a great way to provide a common baseline for authoring documents or presentations within an organization, for a particular type of project or analysis, or for a specific publication.
See Custom Formats
5.2 Custom filters
Based on pandoc filters. See Creating Filters for a guide.
I wrote one myself! I also maintain a bug-fixed version of pandoc-ext/diagram.
6 Slides
Slide output options are here:
TBD.
7 python
7.1 uv support
A minor hack is required:
This is the recommended method. Quarto seems to otherwise find reasonably arbitrary python venvs to work with.
7.2 Jupyter support
Of course Jupyter ends up being a thing. It is a little complicated, as it always is when venturing into the Jupyter Cinematic Universe.
For one, Jupyter notebooks are a valid frontend for Quarto. See the Quarto JupyterLab docs. It is well-documented elsewhere that I dislike Jupyter notebooks as a front-end interface to any system. Fortunately, it also supports normal Quarto documents as a Python front-end, which you will be unsurprised to learn I think is way better.
It is unclear to me how much of a round-trip interaction loop is supported for Jupyter kernels: Quarto renders essentially a static HTML page, so I don’t believe the HTML widgets can be used to interact with the kernel, although they might have some basic animation support via javascript tricks etc. See Jupyter Widgets for some ideas.
8 Academic affordances
As an academic I want certain things in my writing tools, i.e. maths, citations, and cross-references. Quarto knows about these.
In particular, equations are referenced as follows:
Black-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behaviour of financial derivatives, most commonly options:
$$
\frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2}
\frac{\partial^{2} \mathrm C}{\partial \mathrm C^2}
+ \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ =
\mathrm r \mathrm C
$$ {#eq-black-scholes}9 Draft mode
Draft pages are well-supported now in websites, see Website Drafts.
One could probably try some more advanced sub-page draft mode via draft profile:
10 Gotchas
In Nick Tierney’s Quarto for Scientists we see Common Problems with Quarto (and some solutions).
I have some of my own:
If I get an error like this:
Error running filter /Applications/quarto/share/filters/main.lua:
/Applications/quarto/share/filters/main.lua:2479: attempt to index a nil value (local 'el')It means I had a .qmd file containing a plain markdown link with empty text, e.g.
This is valid markdown but not valid Quarto.
Citations inside figure captions do not work, we need to use figure divs e.g. this is no good
But this is fine:
:::{#fig-hallcan2022}
See @Hall2022Can — the attention economy of road signs
:::**UPDATE: maybe I was dreaming about that. It seems to work now.
Corollary: #fig- is a magic prefix for IDs in Quarto, which means you cannot use it for anything else, or that will turn into a figure.
.gitignore for Quarto
By default Quarto adds some stuff to .gitignore, but its list seems incomplete. The following things are not all added by Quarto to my .gitignore file, but I think they should be, because they appear, sometimes temporarily, when I build the site:
10.1 Pre/Post processors
See Project Scripts for information about how to run scripts before or after the build process.
Python is a packaging disaster. I would recommend choosing a packaging system, say uv, and “baking it in” to the definition
So, e.g. my image processing script for this blog is invoked as
To make them work in a continuous integration setting for my website I found it wise to also wrap the scripts with a shell script that sets up the environment.
.qmd files in python
There is a handy script to handle qmd-type files (i.e. with YAML frontmatter) in Python, Python Frontmatter. It is annoying to configure it to roundtrip the YAML correctly; this is what I needed to do.
class CleanYAMLHandler(YAMLHandler):
"""YAML handler that preserves original delimiters and list formatting"""
def export(self, metadata, **kwargs):
return yaml.safe_dump(
metadata,
allow_unicode=True,
default_flow_style=False, # Force block-style lists
sort_keys=False, # Preserve key order
indent=2, # Match Quarto’s indentation
width=80 # Prevent line wrapping
)
# Create our custom handler instance
yaml_handler = CleanYAMLHandler()
with open(post_path, "w") as f:
f.write(
frontmatter.dumps(
post,
handler=yaml_handler,
sort_keys=False,
default_flow_style=None,
)
)11 Incoming
- With Quarto Coming, is R Markdown Going Away? No. - Yihui Xie
- Rob J Hyndman - Monash Quarto Templates (good examples of how to do theming for non-website stuff)
- Prototype Marimo integration: marimo-quarto.