Last week, I gave an introduction to Scientific and Technical Publishing with Quarto at the ETH RSE community event. The Quarto framework works equally well with both of programming-with-data’s favorite languages and has become popular in recent years, yet it was relatively little known in audience. Particularly the discussion with RSE experts from a broad variety of fields has been insightful and great fun. Hence, I decided to not only post a quick debriefing summary of the talk but also to take a closer look at feedback from the audience.
Quarto in a Nutshell
Quarto is a modern framework to help demanding technical and scientific writers create spiffy documents. Outside of academia, its reading-friendly syntax is better received than LaTeX and unlike the output of office world word processors, Quarto’s source is plain text.
Under Quarto’s hood, we find (among other things): a TeX installation, the Swiss army knife document converter pandoc and typst, the new kid on the block that set out to succeed LaTeX. All this flexible rendering power is complemented by an easy-to-use CLI and nice templates for articles, reports, presentations, websites and even entire books.
What’s the biggest deal to me, though, is not that Quarto makes typesetting a little more convenient. (A large chunk of Quarto’s target group never asked for convenience anyway.) Writing scientific and technical documents has just become so much more reproducible, interoperable, inclusive and modular:
- Plain text syntax allows for smooth work with git. At the same time, Quarto’s syntax helps to lure users with less software development affinity. And modern Git platforms continue to make developer collaboration workflows from issue trackers to Kanban boards and Pull Requests so much more accessible.
- Attractive, reading-friendly HTML output displayed on websites, presentations or a growing number of Online books are a true alternative to the same old PDF documents.
- Unlike Software-as-a-Service online editing offerings such as Overleaf, Quarto, and its ecosystem do not depend on a single online platform and allow to work locally, too. I believe the toolbox described above brings another chunk of use cases closer to the open-source software development workflow and possibly even a new group of people. (Stay tuned for my blog post and workshop on Collaborating on Academic Publications Using Modern Git Platforms).
A Glimpse of Quarto
One of Quarto’s strengths is its great, applied documentation, so I am not going to reproduce it here. Yet, let me give you a quick glimpse of Quarto anyway.
---
title: "Most Basic Quarto Document"
format: html
---
## This Is Just a Markdown Section Header
At render time this .qmd file is turned into a markdown file
and then processed into an HTML document.
Text can contain code chunks in various languages that are
executed through their respective interpreters.
### Subheader 1
more text.
### Subheader 2
even more text.
The most basic Quarto document above mingles markdown with a .yaml header. This header contains document-level information, including information such as the output format that is needed for the rendering process. But most notably, Quarto mingles the markdown formatted text with source code of an interpreted programming language that is executed at render time. As you can see when you compare the source code of this blog post with the post itself, code chunks are simply replaced with their execution results.
From Presentations and Reports to Websites and Books
When quarto projects get complex beyond single documents, project-level information is stored in a _quarto.yml file. In a book project, for example, the _quarto.yml file sources all chapters, including references. This allows you to easily re-order chapters, split work among authors, and alternate between different output formats. Here’s the quarto file of the online version of my forthcoming Research Software Engineering book. The _quarto.yml file contains book-level information such as title, subtitle or author as well as feature activation flags, e.g., search, and a navigation tree to all chapter sources. Quarto books allow for a plethora of configuration options that are a testimony of years of publishing experience and knowing what book authors need in the process of writing a book. Quarto was a catalyst to getting my own book done, pushing around chapters and content across chapters and several iterations of fine-tuning have been facilitated through quarto. Imo, it is also noteworthy that with CRC/Chapman&Hall, a large publisher, not only accepted a Quarto-based draft for publication but even offered their own quarto template for quarto authors.
project:
type: book
book:
title: "Research Software Engineering"
subtitle: "A Guide to the Open Source Ecosystem"
author: "Matthias Bannert"
date: "7/12/2022"
search: true
sharing: [twitter]
chapters:
- index.qmd
- intro.qmd
- stack-developer-toolkit.qmd
- programming.qmd
- interaction.qmd
- version-control.qmd
- data-management.qmd
- infrastructure.qmd
- automation.qmd
- community.qmd
- publishing.qmd
- case-studies.qmd
- appendix.qmd
- references.qmd
bibliography: references.bib
execute:
freeze: true
format:
html:
theme: cosmo
Typst Support
Admittedly, I needed Roland Siegbert from ETH Quantum Device Lab and my colleague Minna to become aware of the appeal of Quarto’s typst support, but now I feel like it’s one of Quarto’s most promising new features. If you, like me, got your scientific writing stack together when iPhone 5s were hot and Gangnam style tested our nerves, you may appreciate a quick catch-up.
Typst is markup-based typesetting system that set out to become an alternative to both good ol’ LaTeX and office tools like Google Docs or Word. It does so with a considerably simpler syntax and faster rendering than LaTeX, a pleasure-to-use approach and clean, technical templates, including popular academic outlets and the ability to create custom templates. The below syntax is taken from the typst own introduction quickly renders to a beautiful two column layout.
#let conf(title, doc) = {
set page(
paper: "us-letter",
header: align(
right + horizon,
title
),
...
)
set par(justify: true)
set text(
font: "Linux Libertine",
size: 11pt,
)
// Heading show rules.
...
columns(2, doc)
}
#show: doc => conf(
[Paper title],
doc,
)
= Introduction
#lorem(90)
The cool thing about quarto typst support is that you can use both raw typst syntax if you’re already a heavy typst user, or quarto markdown if you’re rather familiar with Markdown. In the latter case, quarto render your-file.qmd will just do the job: create an intermediate typst file create a PDF from there, clean up the intermediate file, done.
Ah, and if you’re into machine learning and ever needed another reason to invest some time into Quarto, you can now host quarto sites on Hugging Face using the new quarto space template :)
