Typst Format

Pre-release Feature

This feature is new in the upcoming Quarto 1.4 release. To use the feature now, you’ll need to download and install the Quarto pre-release.

Quarto v1.4 includes support for the typst output format. Typst is a new open-source markup-based typesetting system that is designed to be as powerful as LaTeX while being much easier to learn and use. Typst creates beautiful PDF output with blazing fast render times.

Getting Started

To try out the typst format:

Download and install the latest pre-release of Quarto 1.4 (ensure you have installed Quarto v1.4.145 or higher).

Create a document that uses format: typst. For example:

---
title: "My document"
format: typst
---

Hello, typst!

Rendering or previewing this document will invoke the Typst CLI to create a PDF from your markdown source file. Note that Quarto includes version 0.8 of the Typst CLI so no separate installation of Typst is required.

Typst Format

When authoring a Typst document you’ll be using a Quarto format that is in turn based on a Typst template, which defines its structure, layout, and available options. The default Typst format and template that ships with Quarto (format: typst) includes options for specifying title, author, and abstract information along with basic layout and appearance (numbering, margins, fonts, columns, etc.).

The following options are available for customizing Typst output:

Option	Description
`title`	Main document title
`author`	One or more document authors.
`date`	Date of publication
`abstract`	Article abstract
`toc`	Include a table of contents.
`number-sections`	Apply numbering to sections and sub-sections
`section-numbering`	Schema to use for numbering sections, e.g. `1.1.a`.
`margin`	Margins: `x`, `y`, `top`, `bottom`, `left`, `right`. Specified with units (e.g. `y: 1.25in` or `x: 2cm`).
`papersize`	Paper size: `a4`, `us-letter`, etc. See the docs on paper sizes for all available sizes.
`fontsize`	Font size (e.g., `12pt`)
`section-numbering`	Schema to use for numbering sections, e.g. `1.1.a`.
`columns`	Number of columns for body text.
`include-in-header`	`.typ` file to include in header
`include-before-body`	`.typ` file to include before body
`include-after-body`	`.typ` file to include after the body
`keep-typ`	Keep the intermediate `.typ` file after render.
`bibliography`	`.bib` file to use for citations processing
`bibliographystyle`	Style to use with Typst’s bibliography processing - See the doc about bibliography to see supported style.
`citeproc`	If `true`, Pandoc’s citeproc will be used for citation processing instead of Typst’s own system (which is the default).
`csl`	`.csl` file to use when Pandoc’s citeproc is used.

For example:

---
title: "My Document"
format:
  typst:
    toc: true
    section-numbering: true
    columns: 2
bibliography: refs.bib
bibliographystyle: chicago-author-date
---

See the section below on Custom Formats for details on creating your own specialized formats for use with Typst.

Bibliography

Typst comes with its own citation processing system for Bibliography and using format: typst defaults to it. If you prefer to use Pandoc’s citation processing with a .csl file (e.g to use same .csl for a HTML and PDF document), set citeproc: true explicitly in YAML header.

---
title: Typst doc using citeproc
format: typst
citeproc: true
bibliography: refs.bib
csl: https://www.zotero.org/styles/apa-with-abstract
---

Typst Blocks

If you want to change the appearance of blocks using native Typst #block() calls, you can add the .block class to a Div and provide whatever arguments are appropriate. For example:

::: {.block fill="luma(230)" inset="8pt" radius="4pt"}

This is a block with gray background and slightly rounded corners.

:::

This gets compiled to

#block(fill:luma(230), inset=8pt, radius=4pt, 
[This is a block with gray background and slightly rounded corners])

Raw Blocks

If you want to use raw typst markup, use a raw typst block. For example:

```{=typst} 
#set par(justify: true)

== Background 
In the case of glaciers, fluid dynamics principles can be used to understand how the movement and behavior of the ice is influenced by factors such as temperature, pressure, and the presence of other fluids (such as water).
```

To learn more about typst markup, see the tutorial here: https://typst.app/docs/tutorial/.

Typst File (`.typ`)

The rendering process produces a native Typst file (.typ) which is then compiled to PDF using the Typst CLI. This intermediate file is then automatically removed. If you want to preserve the .typ file, use the keep-typ option. For example:

---
title: "My Document"
format:
  typst:
    keep-typ: true
---

You can compile a .typ file to PDF directly using the quarto typst compile command in a terminal. For example:

Terminal

$ quarto typst compile article.typ

The quarto typst command uses the version of Typst built in to Quarto and support all Typst CLI actions and flags. For example, to determine the version of Typst embedeed in Quarto:

Terminal

$ quarto typst --version

Known Limitations

Callouts are not yet supported (they become block quotes with a bold heading)
Advanced page layout (panel layout, margin layout, etc.) does not work
Various other small things might not yet be implemented, please let us know if you see things that could use improvement!

Custom Formats

You can create highly customized output with Typst by defining a new format based on a custom Typst template. The Typst team has created several useful templates, a few which which have been adapted for use with Quarto as custom formats. These formats include:

Format	Usage
Poster	`quarto use template quarto-ext/typst-templates/poster`
IEEE	`quarto use template quarto-ext/typst-templates/ieee`
AMS	`quarto use template quarto-ext/typst-templates/ams`
Letter	`quarto use template quarto-ext/typst-templates/letter`
Fiction	`quarto use template quarto-ext/typst-templates/fiction`
Dept News	`quarto use template quarto-ext/typst-templates/dept-news`

The source code for these formats is available at https://github.com/quarto-ext/typst-templates.

To create a new custom Typst format (or package an existing Typst template for use with Quarto) use the quarto create command to get started:

Terminal

$ quarto create extension format

Then, choose typst as the base format and provide a name for the extension (e.g. letter). A sample Typst format extension will be created based on the code used in the default template that ships with Quarto. It will include the following files which you can edit to implement your custom format:

To implement the custom format, edit the following files:

File	Description
`_extension.yml`	Basic extension metadata (name, author, description, etc.) and format definition.
`README.md`	Documentation on how to install and use the format.
`template.qmd`	A starter document that demonstrates the basics of the format.
`typst-template.typ`	The core Typst template function (documentation on creating Typst templates can be found here: https://typst.app/docs/tutorial/making-a-template/).
`typst-show.typ`	File that calls the template’s function (mapping Pandoc metadata to function arguments).

Additional resources you might find useful when creating custom formats include:

The official Typst tutorial on Making a Template
List of third party templates from the Awesome Quarto repo.

Template Partials

Note

This section covers advanced customization of Typst format output and can be safely ignored unless you have found the method of defining custom Typst formats described above too limited.

Above we describe a method of creating a Typst format based on specifying two template partials (typst-template.typ and typst-show.typ). These partials customize components of the default Typst Pandoc template, but leave some of the core scaffolding including definitions required by Pandoc for its Typst output as well as handling of bibliographies and footnotes (this means that your own custom Typst formats do not need to explicitly handle them).

If you would like to fully override the Pandoc template used for rendering Typst, use the template option in your custom format (rather than template-partials) and provide an alternate implementation of the default template. For example, your _extensions.yml might look like this:

_extensions.yml

---
title: Typst Custom Format
author: Jane Smith
version: "0.2.0"
quarto-required: ">=1.4.11"
contributes:
  formats:
    typst:
      template: template.typ
      template-partials:
        - typst-template.typ
        - typst-show.typ
---

Use the source code of the default template as a starting point for your template.typ. Note that you can call all of the template partials provided by Quarto (e.g. biblio.typ() or notes.typ() from within your custom template implementation.

The AMS format provides an example of redefining the main template (in that case, it is to prevent automatic bibliography processing by Quarto in deference to the built-in handling of the Typst AMS template).

Getting Started

Typst Format

Bibliography

Typst Blocks

Raw Blocks

Typst File (.typ)

Known Limitations

Custom Formats

Template Partials

Typst File (`.typ`)