Quarto

1 Vibes

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 more 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. Using hugo to render my website sounded like it might provide an easy migration path for my blogdown, but it turned out not to be particularly good for my approach. It breaks the tight integration with Pandoc which is IMO a major advantage of Quarto over blogdown, and takes you into the weeds of a less-er known esoteric system.

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 that the price of simple access to features was a massive blowout in time to render.

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 which I endorse. Maybe that means it is good? Quarto supports Docusaurus. Let me know if you have any luck with it; I’ve done enough migrations for now.

5 Customisation

6 Slides

Slide output options are here:

• Revealjs Options
• Revealjs

TBD.

7 python

# Activate the virtual environment
source .venv/bin/activate
quarto render

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.

• Cross References
• Citations & Footnotes

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:

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

10 Gotchas

In Nick Tierney’s Quarto for Scientists we see Common Problems with Quarto (and some solutions).

I have some of my own:

Error running filter /Applications/quarto/share/filters/main.lua:
/Applications/quarto/share/filters/main.lua:2479: attempt to index a nil value (local 'el')

[](https://github.com)

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

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

See @Hall2022Can — the attention economy of road signs
:::

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

  post-render:
    - uv rn massage_header_img

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.