quarto-preprint

A Quarto extension for creating PDF documents with Typst

Examples

Default output	theme: jou output	Full-width content	Single-column appendices

Overview

“An article about computational science in a scientific publication is not the scholarship itself, it is merely advertising of the scholarship. The actual scholarship is the complete software development environment and the complete set of instructions which generated the figures.”

–Buckheit and Donoho (1995, paraphrasing Jon Claerbout)

Quarto is "An open-source scientific and technical publishing system" for writing reproducible documents that combine computations and prose written in markdown into HTML, PDF, Word, and other outputs. For many R users, Quarto is a successor of R Markdown but with a broader scope and better support for different output formats and computational content in other languages.

quarto-preprint is a Quarto extension that provides the preprint-typst output format. When using this format, Quarto renders your document into PDF using Typst, a modern replacement for LaTeX. preprint-typst builds on the standard Quarto Typst template and enables separated author-affiliation formatting, additional metadata variables for scholarly writing, opinionated but customizable typesetting, improved two-column layouts (including full-width floats), appendices, and more. In addition, preprint-typst aims to

• Be fast: Typst creates PDF files very quickly
• Just Work: No LaTeX installation required (Typst ships with Quarto)
• Be 100% Quarto compatible: Switch between output formats without changing content
• Have rich features: Separated author-affiliation formatting, two-column layouts, full-width floats, appendices

Installation

Add to existing Quarto project

quarto add mvuorre/quarto-preprint

This creates a _extensions/preprint/ directory in your project. The preprint-typst format is then ready to use.

Start new Quarto project

quarto use template mvuorre/quarto-preprint

This creates a new project directory with a starter document, _quarto.yml configuration file, and example bibliography.bib file.

Note that quarto-preprint is the name of the Quarto extension, and preprint-typst is the name of the Quarto output format.

Configuration

Quarto document output is configured through YAML front matter metadata. To use preprint-typst as the output format, include format: preprint-typst in the front matter. Here is a minimal example that specifies a title, a table of contents, and two output formats:

---
title: "My Paper"
toc: true
format:
  preprint-typst:
    wordcount: true
  html:
    theme: cosmo
---

Your content here...

Front matter variables can be shared across output formats (such as toc above) or specific to them (like wordcount above). See Quarto’s guide to writing scholarly documents and Quarto’s Typst format documentation.

preprint-typst supports all of Quarto’s YAML front matter variables for scholarly writing and Typst documents. Below, we document the additional variables supported by preprint-typst.

preprint-typst extension options

preprint-typst enables these custom variables for Typst output:

• running-head (string) - Short title text displayed in page headers
  • Example: running-head: "Short Title"
• authornote (string) - Text appearing after corresponding author information
  • Example: authornote: "Author affiliations and contact"
• wordcount (boolean) - Display word count below abstract
  • Example: wordcount: true
• theme (string) - Select a theme ("default", "jou")
  • Example: theme: jou creates an optimized two-column layout
• functions (array) - Enable Typst functions in Quarto divs [typst-function]
  • Example: functions: ["place"]
• corresponding-text (string) - How to refer to corresponding authors (default: "Send correspondence to:")
  • Example: corresponding-text: "Corresponding authors:" displays as "Corresponding authors: Name, email."
• bibliography-title (string) - Title of bibliography section [Typst, Quarto]
  • Only works when using Typst's own citation processing system
  • Example: bibliography-title: Works cited

Typography

• monofont (string) - Font family for code [Quarto]
  • Example: monofont: "Monacy"
• linkcolor (string) - Color for hyperlinks [Quarto, Typst]
  • Example: linkcolor: "blue" or linkcolor: "#0066cc"

Layout

• line-number (boolean) - Enable line numbers [Typst]
  • Example: line-number: true
  • This is simplified to a boolean instead of allowing custom numbering as per Typst.
• leading (string) - Line height/spacing between lines [Typst]
  • Example: leading: "0.5em"
• spacing (string) - Vertical spacing between paragraphs [Typst]
  • Example: spacing: "0.6em"
• first-line-indent (string) - Indentation for paragraph first lines [Typst]
  • Example: first-line-indent: "1.8em"
• all (boolean) - Whether to indent all paragraphs (including first in section) [Typst]
  • Example: all: false
• col-gutter (string) - Horizontal spacing between columns [Typst]
  • Example: col-gutter: "4.2%" or col-gutter: "2em"

Language

• lang (string) - Document language [Quarto, Typst]
  • Example: lang: "en" or lang: "de"
• region (string) - Document region [Quarto, Typst]
  • Example: region: "US" or region: "GB"

Bibliography & citations

Using Typst's own citation processing

Typst has its own citation processing system, whose behavior you can customize with bibliography-title, bibliographystyle.

Using Pandoc (recommended)

However, to allow better bibliography customization via the csl YAML variable, and use of Quarto’s #refs div, you must use Pandoc's citation processing with citeproc: true. When citeproc: true, you can load a CSL file directly from an URL, and add the References section anywhere in your document (e.g. before any appendices) using Quarto’s #refs div:

# References

::: {#refs}
:::

to display the bibliography section anywhere in the document (for example, before any appendices).

Note. There is currently a bug in Typst whereby some CSL styles aren't properly applied (typst/typst#2639). For example, the APA style lacks hanging indents. Until this is fixed in Typst, you can customize the display of the references section by including custom Typst code that targets any blocks in the document. For example, to add hanging indents, write:

format:
  preprint-typst:
    include-before-body:
      - text: "#show <refs>: set par(hanging-indent: 1.4em)"

Citation management

Quarto documents require citations in a separate .bib file. The vscode-zotero VS Code plugin helps with inserting in-text citations and managing the .bib file. The plugin works in all VS Code based editors, including Positron.

Extra features

Full-width content

You can include page-wide figures (or any other content) in documents that have more than one column. To do so, wrap the content in a Quarto div like this:

::: {.place arguments='top, scope: "parent", float: true'}
Any content here will span the whole page.
:::

The above uses the Typst’s place() function through the typst-function Quarto extension to place the div’s content in "parent" scope (the document page is the column’s parent) and must specify that Typst should treat the content as a float. The first argument top specifies that the content should be placed on the top of the page; use bottom to place it on the bottom.

Since this feature uses a Quarto div, if you want to include further divs inside this div, use more colons. For example:

:::: {.place arguments='top, scope: "parent", float: true'}

::: {#fig-wide fig-cap="Full-width figure"}
{{< placeholder 600 200 format=svg >}}
:::

Other full-width content. Note linebreaks here (between the colons and content) are important.

::::

Note: The function only takes effect in Typst documents, other formats (e.g. HTML) will display the content with no extra formatting.

Appendices

To include an appendix, include the following raw Typst block in your Quarto document, followed by your appendix content:

```{=typst}
#show: appendix.with()
```

# Appendix title

Appendix content.

Note: If you want the appendix to appear as an appendix in HTML output as well, add the .appendix class to the headings. Appendices are an experimental feature. They are provided through a custom Typst function, and their implementation and functionality may change as Quarto’s Typst integration matures.

Get help & contribute

Send your comments, bug reports, and pull requests to https://github.com/mvuorre/quarto-preprint. If you’re reporting a bug, please include a reproducible example / full details of what you’re trying to do, how, and what goes wrong.