quarto-preprint: A Quarto Typst extension for efficient typesetting of computationally reproducible manuscripts

Author

Affiliation

Matti Vuorre

Tilburg University

Abstract

Quarto is a “scientific and technical publishing system”, e.g. for computationally reproducible manuscripts. It is both a markup language that extends pandoc markdown and a program that renders Quarto markdown sources to a variety of formats including PDF, MS Word, HTML, presentations, ePub, and many more. The source code can include prose (this text), math (\(\sqrt{2}\)), code evaluation ({r} sqrt(2) renders to 1.414), scholarly metadata, and more. The look and feel of the output documents can be controlled within the source document, or by using an extension. quarto-preprint is such an extension, designed to produce neat documents quickly with minimum effort. It is called “quarto-preprint” because it facilitates multiformat rendering and switching to journal-specific formats by being 100% Quarto standards compliant. It also produces basic MS Word documents to facilitate collaboration and/or further WYSIWYG editing. This document is both the manual and an example document using quarto-preprint.

Keywords

Quarto, Typst, preprints, communication, typesetting, tools

Preface

Note

You are viewing HTML output of a Quarto document. To see quarto-preprint outputs in PDF or MS Word, click the links here or in the right side bar.

I hope that quarto-preprint could help encourage scholars to think more proactively about the roles that preprints play in the modern scholarly communication landscape (Sever 2023; Syed 2024; Moshontz et al. 2021; Ahmed et al. 2023).

Why might one use the quarto-preprint extension? One, it renders documents from Quarto markdown to PDF using Typst¹, and therefore is very fast in doing so. Typst doesn’t require complicated LaTeX installations and so is practically easier to use than other PDF-producing methods. Typst also simplifies the development and codebase of templates and Quarto formats, and thus makes edits, bug fixes, forks, and new features easier. Second, quarto-preprint aims to be 100% Quarto standards compliant: Users don’t need to adapt their source code in any way when they switch to other formats, such as other journal extensions, or completely different output formats such as HTML².

This document is both the quarto-preprint manual, and an example document making use of it. You can find its Quarto markdown source code here. You can view the latest version of the PDF output here (MS Word, HTML).

A Quarto example

Here are the contents of a basic Quarto markdown file, called myfile.qmd:

---
title: Example preprint
author:
  - name: Matti Vuorre
    email: mjvuorre@uvt.nl
    orcid: 0000-0001-5052-066X
    affiliation:
      - ref: 1
affiliations:
  - id: 1
    name: Tilburg University
    department: Department of Social Psychology
bibliography: bibliography.bib
format: pdf
---

This text will end up in the rendered .html file. Exciting [@r2024]!

This source code renders (e.g. in RStudio or CLI) to Figure 1 (left).

Figure 1: A cropped version of a basic Quarto .pdf document (left) and a preprint Quarto .pdf document (right).

However, Figure 1 (left) lacks several features that we’ve come to expect from scholarly outputs, such as authors’ affiliations. quarto-preprint includes many such features. Changing format: pdf in the above source code to format: preprint-typst instructs Quarto to use the extension, which produces the PDF document in Figure 1 (right).

That is, quarto-preprint is a Quarto extension that provides a Quarto format called preprint-typst, which formats your Quarto source—which can be prose, code, math, tables, figures, etc.—to a pleasant looking .pdf via Typst.

quarto-preprint manual

The preprint Quarto extension provides functionality through Quarto metadata, some of which is mapped to a Typst template and its variables. Therefore, if you cannot find the information you’re looking for in this manual, consult either the Quarto or Typst documentation.

In the documentation below, we have divided the YAML metadata options to two sections. First are options that are common to most if not all Quarto formats. Second are options specific to the Typst format and the quarto-preprint Typst format extension.

Common Quarto options

The code snippet above showed YAML metadata between triple-dashes. This YAML metadata can be used to control the output such as fonts, authors, whether to include a table of contents, and many more. We list and explain these options, with examples, below in roughly a decreasing order of importance to typical scholarly manuscripts.

Title

title: "*preprint*: A Quarto Typst extension for computationally reproducible manuscripts"

Title of the manuscript. Required; needs to be in quotation marks only if it includes special characters such as colons. See relevant Quarto documentation.

Authors & affiliations

author:
  - name: Matti Vuorre
    email: mjvuorre@uvt.nl
    orcid: 0000-0001-5052-066X
    url: https://www.tilburguniversity.edu/staff/m-j-vuorre
    affiliation:
      - ref: 1
affiliations:
  - id: 1
    name: Tilburg University
    department: Department of Social Psychology

Authors and their affiliations as explained in Quarto’s scholarly writing documentation.

A few features are not yet included. The corresponding: true syntax for indicating corresponding authors does not work. To indicate a corresponding author, specify an email for that author (as in above example). The equal-contributor: true option is not yet implemented.

Abstract, keywords, & date

abstract: |
  This document and its source code (`manual.qmd`) illustrate uses of various [Quarto](https://quarto.org) & *preprint* extension features, such as weaving R code [@r2024] and prose.
keywords: 
  - list 
  - keywords
  - here
  - but not
  - too many
date: "`r Sys.Date()`"

The document’s abstract can include multiple paragraphs, Markdown, maths, references, and more. A list of keywords and the document’s date can be added. Above example shows how to include the current date using R.

Citation information

citation:
  type: article-journal
  container-title: "PsyArXiv"
  doi: "10.31234/osf.io/z3ejx"
  url: https://osf.io/preprints/psyarxiv/z3ejx

This information is used by Quarto to include the document’s citation information to various formats and the document’s metadata. See relevant Quarto documentation.

Other common options

bibliography: bibliography-manual.bib
linkcolor: blue
mainfont: Fira Sans
fontsize: 10pt
toc: true
toc_depth: 2
toc_title: "Contents of the document"
code-links: repo

The above shows how to specify a bibliography file, color for links in the document, the main font and its size, table of contents (and its options). The code-links option is useful when the output formats include HTML.

Format

You can specify one or more formats, and settings specific to them, under the format key. See here for Quarto’s Typst-specific format options.

format:
  preprint-typst: 
    keep-typ: true

Typst & preprint-extension options

running-head: "*preprint* Quarto extension manual"
branding: psyarxiv
authornote: This is an example author note.

running-head should be a text string and is used as the document’s running head.

branding adds a specified preprint service’s logo to the document. Currently only “psyarxiv” is a valid value.

authornote allows adding information to the footer of the first page.

Typst geometry, layout, and formatting options

leading: 0.6em
spacing: 1em
section-numbering: none
bibliography-title: "References"
bibliography-style: "apa"
margin:
  x: 1cm
  y: 3cm

• leading
  • Space between lines of text https://typst.app/docs/reference/model/par/#parameters-leading
• spacing
  • Space between paragraphs https://typst.app/docs/reference/layout/block/#parameters-spacing
• section-numbering
  • In Typst format e.g. “1.1”, do not include or leave empty (““) to not number sections.
• first-line-indent
  • https://typst.app/docs/reference/model/par/#parameters-first-line-indent
• margin
  • Page margins https://typst.app/docs/reference/layout/page/#parameters-margin
• paper
  • https://typst.app/docs/reference/layout/page/#parameters-paper
• lang
  • https://typst.app/docs/reference/text/text/#parameters-lang
• region
  • https://typst.app/docs/reference/text/text/#parameters-region
• bibliography-title: “References”
• bibliography-style: “apa”

Example content

Let us first take a look at body text and headings.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Enim sed faucibus turpis in. Nec dui nunc mattis enim ut tellus. Bibendum ut tristique et egestas quis ipsum suspendisse ultrices gravida. Convallis posuere morbi leo urna. Sed velit dignissim sodales ut eu sem integer vitae justo. Convallis posuere morbi leo urna molestie at elementum eu facilisis. Aliquam sem et tortor consequat. Quam viverra orci sagittis eu. Sed arcu non odio euismod lacinia at quis risus sed. Egestas dui id ornare arcu odio ut sem. Lorem ipsum dolor sit amet consectetur.

Heading level 2

Eget arcu dictum varius duis at. Netus et malesuada fames ac turpis. Pellentesque sit amet porttitor eget. Egestas tellus rutrum tellus pellentesque eu tincidunt tortor. Risus quis varius quam quisque id diam. Vel pretium lectus quam id leo in vitae. Sit amet aliquam id diam maecenas ultricies mi eget mauris. Auctor urna nunc id cursus metus aliquam eleifend. Arcu dictum varius duis at consectetur lorem. Tempus iaculis urna id volutpat lacus laoreet non. Adipiscing elit ut aliquam purus sit amet. At auctor urna nunc id cursus metus aliquam. Pharetra vel turpis nunc eget lorem dolor.

Heading level 3

Tristique et egestas quis ipsum suspendisse ultrices gravida dictum fusce. Mauris commodo quis imperdiet massa tincidunt nunc pulvinar. Commodo elit at imperdiet dui accumsan sit amet nulla. Consectetur lorem donec massa sapien faucibus. In vitae turpis massa sed elementum tempus egestas sed sed. Aliquam faucibus purus in massa tempor. Dignissim diam quis enim lobortis scelerisque fermentum dui faucibus in. Montes nascetur ridiculus mus mauris vitae ultricies leo. Sociis natoque penatibus et magnis dis parturient montes nascetur.

Heading level 4

Consectetur libero id faucibus nisl. Consequat interdum varius sit amet mattis vulputate enim. Amet mattis vulputate enim nulla aliquet porttitor lacus luctus. Mauris augue neque gravida in fermentum et sollicitudin ac. Pharetra diam sit amet nisl suscipit adipiscing bibendum est ultricies. Nisi quis eleifend quam adipiscing. Diam ut venenatis tellus in. Dignissim enim sit amet venenatis urna cursus eget. Hac habitasse platea dictumst quisque sagittis. In fermentum et sollicitudin ac orci phasellus egestas tellus rutrum.

Heading level 5

Aliquam faucibus purus in massa tempor nec feugiat nisl pretium. Malesuada proin libero nunc consequat interdum varius. Vulputate dignissim suspendisse in est. Congue eu consequat ac felis donec et odio pellentesque diam. Viverra justo nec ultrices dui sapien. Faucibus vitae aliquet nec ullamcorper sit amet risus. Metus aliquam eleifend mi in. Risus quis varius quam quisque id diam vel quam. Et malesuada fames ac turpis egestas integer eget aliquet.

Floats

Tables

Tables are still the achilles heel of Typst (and any cross-format output, really). However, basic tables are more than possible, and below is an example table produced in R with the tinytable package (Table 1). Note that some features of tables, such as footnotes, are not yet implemented in Typst / Quarto.

tinytable::tt(
  head(data, 2),
  digits = 2
)

Table 1: Table created with tinytable::tt()

x	y
-0.63	1.4
0.18	-0.1

Table 2: Table created with knitr::kable()

x	y
-0.63	1.36
0.18	-0.10

Figures

Below is an example figure created in R (Figure 2).

Figure 2: Example R scatterplot.

Quarto markdown features

Maths

LaTeX math notation is automatically converted to Typst and as such works just fine either inline (\(y_i = \alpha + \beta x_i + \epsilon_i\)) or in display mode (Equation 1):

\[ f(x \mid \mu, \sigma^2) = \frac{1}{\sqrt{2\pi \sigma^2}} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right) \tag{1}\]

Block quotes

To insert a quote block, prepend a paragraph with >:

A quote: “Elit ullamcorper dignissim cras tincidunt lobortis feugiat vivamus at.”

Callouts

Callout blocks, such as Tip 1, can be useful for highlighting content, such as one might do in a box that defines key terms, etc.

Tip 1: All kinds of markup

This is basic markdown: **bold text** & ~subscript~.

This is basic markdown: bold text & _subscript.

Code listings

Code listings can also be cross-referenced (Listing 1).

Listing 1: R code for pRos.

1+1
## [1] 2

Help & contributing

Send your bug reports and pull requests to https://github.com/mvuorre/quarto-preprint.

References

Ahmed, Abubakari, Aceil Al-Khatib, Yap Boum, Humberto Debat, Alonso Gurmendi Dunkelberg, Lisa Janicke Hinchliffe, Frith Jarrad, et al. 2023. “The Future of Academic Publishing.” Nature Human Behaviour, July, 1–6. https://doi.org/10.1038/s41562-023-01637-2.

Moshontz, Hannah, Grace Binion, Haley Walton, Benjamin T. Brown, and Moin Syed. 2021. “A Guide to Posting and Managing Preprints.” Advances in Methods and Practices in Psychological Science 4 (2): 25152459211019948. https://doi.org/10.1177/25152459211019948.

Sever, Richard. 2023. “Biomedical Publishing: Past Historic, Present Continuous, Future Conditional.” PLOS Biology 21 (10): e3002234. https://doi.org/10.1371/journal.pbio.3002234.

Syed, Moin. 2024. “Valuing Preprints Must Be Part of Responsible Research Assessment.” Meta-Psychology 8 (March). https://doi.org/10.15626/MP.2023.3758.

Footnotes

1. “Typst is a new markup-based typesetting system for the sciences. It is designed to be an alternative both to advanced tools like LaTeX and simpler tools like Word and Google Docs.”

2. There are a few small features that likely won’t show up in other formats, such as branding (see below), but their inclusion or exclusion in the metadata doesn’t impact how sources are rendered to other formats.