Quarto

Swiss army knife for hand-whittling scientific reports, slides and blogs

May 1, 2022 — September 5, 2024

academe
faster pussycat
how do science
javascript
julia
language
making things
plain text
premature optimization
python
R
writing
Figure 1

A new entrant to the world of scientific notebooks and academic blogging. Kind of a competitor/complement to jupyter and blogdown, quarto which unites these other system and also shares some developers/tools/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, crossrefs, figure panels, callouts, advanced layout, 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 layout, 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, as regards 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 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 us content creators, but not necessarily easy for our readers, because they become slow and bloated when the website gets big.

2 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 will 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.

3 Websites via docusaurus

Docusaurus is a static site generator for documentation sites. It is not as homegrown as the built-in one, and has developers who really hate complexity. Maybe that means it is good? Quarto supports Docusaurus.

4 Customization

4.1 Build a custom format

If you hate 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, pdf, docx) already available. Custom formats can provide default document options, style-sheets, 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

4.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.

4.3 Pre/post processors

See Project Scripts.

5 Slides

Slide output options are here:

TBD.

6 Jupyter support

Of course jupyter ends up being a thing. It is a little complicated, of course, 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 support 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.

7 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 behavior 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}

8 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:

::: {.content-visible when-profile="draft"}
This content will only appear in the advanced version.
:::

9 Gotchas

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.

[](https://github.com)

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

![See @HallCan2022 — the attention economy of road signs](/images/science.abm3427-fa.avif)

But this is fine:

:::{#fig-hallcan2022}
![](/images/science.abm3427-fa.avif)

See @HallCan2022 — 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

Per 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:

/.temp_quarto_timestamp
*.feed-full-staged
*-listing.json
/site_libs
/_site
*.html
.jupyter_cache
*.quarto_ipynb

10 Incoming