Quarto

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

May 1, 2022 — February 29, 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.

C&C codebraid.

1 Quarto integrated website system

This section got so big I broke it out into the post quarto integrated website system.

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?

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! I render TikZ in quarto using the excellent filter danmackinlay/quarto_tikz that I wrote before I noticed that there was already a better one, 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.

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

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

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

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.

9 Incoming