PDFs with Typst

Hello, Typst!

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 is built to simplify the process of creating beautiful, professional PDFs. It uses a markup-based system, which means you write plain text and code to define your document’s structure and style, just like you would with Quarto or Markdown.

Hello, Typst!

To use Typst with Quarto, set the format in the YAML of your Quarto document:

---
format: typst
---

How do you use Typst with Quarto? You just need to specify it as your output format in the YAML header of your Quarto document. This is the default page layout you’ll get: a clean, single-column PDF.

Building PDFs

Page layout

Control the size of the page (papersize), the page margins (margin), and the number of columns used for page content (columns):

---
title: Page Layout
format:
  typst:
    papersize: a5
    margin:
      x: 1cm
      y: 1cm
    columns: 2
---

One of the great things about Typst is how easily you can customize your PDF’s appearance. You can control the page size, margins, and even the number of columns directly from your YAML. For example, to create a two-column, A5-sized document with one-centimeter margins, you can use this code.

Margins

Edit the margin’s horizontal direction (x) and vertical direction (y):

margin:
  x: 1.25in
  y: 1.25in

Can also use relative length:

margin:
  left: 10%

If you want more granular control, you can define your margins for the horizontal and vertical directions separately. You can use standard units like inches or centimeters, as shown here.

Paper Size

papersize: us-letter

Typst supports a wide range of paper sizes. Instead of just us-letter or a4, you have a lot of options. Typst’s documentation has a full list of all the supported sizes. It’s a very comprehensive set of options.

More options

Table of contents

toc: true
toc-depth: 2

Section numbering

number-sections: true

Use number-depth:

number-depth: 3

There are also a ton of other options you can set in your YAML. For example, you can easily add a table of contents and control its depth. Or you can add section numbering to automatically number your headings. You can even specify the depth of the numbering.

Typst blocks

Add a .block class to change appearance of blocks:

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

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

:::

Typst also lets you create custom blocks to highlight specific content. You can add a .block class to your markdown and change its appearance with a few simple attributes, like fill, inset, and radius.

Typst and fonts

Check what fonts are available on your system with:

Terminal

quarto typst fonts

Set additional paths using font-paths:

---
format: 
  typst:
    font-paths: myfonts
---

With Typst, you can use any font available on your system. To see what fonts are installed, just run this command in your terminal. If you have custom fonts, you can tell Typst where to find them by setting the font-paths option in your YAML.

Branding Typst with brand.yml

One of the most powerful features of Quarto is the ability to use a _brand.yml file to manage your brand identity across multiple projects.

Color

Use colors from the _brand.yml file in Typst using brand-color:

::: {.block fill="brand-color.primary" inset="8pt" radius="4pt"}

This is a block with the primary color and slightly rounded corners.

:::

This includes colors. You can reference colors defined in your _brand.yml file directly in your Typst documents. Here, we’re using a block with a fill color from our brand’s primary color palette.

Fonts

Quarto will download fonts from Google Fonts and put them in the Typst fonts path if they are specified in the typography.fonts section of _brand.yml using source: google.

_brand.yml

typography:
  fonts:
    - family: Libre Franklin
      source: google
      weight: [400, 700]

  base:
    family: Libre Franklin
    weight: 400

  headings:
    family: Libre Franklin
    weight: 700
    color: dark-purple

Quarto can even handle fonts for you. If you specify a font from Google Fonts in your _brand.yml file, Quarto will automatically download it and make it available to Typst. This is an example of what that looks like in your _brand.yml:

Fonts

	base	headings	title1	subtitle	monospace-inline	monospace-block	link
family	✓	✓	✓	✓	✓	✓	NA
size	✓	NA	NA	NA	✓	✓	NA
weight	✓	✓	✓	✓	✓	✓	✓
style	NA	✓	✓	✓	NA	NA	NA
color	✓	✓	✓	✓	✓	✓	✓
background-color	NA	NA	NA	NA	✓	✓	✓
decoration	NA	NA	NA	NA	NA	NA	✓
line-height	✓	✓	✓	✓	NA	✓	NA

This table shows the various font properties you can control within your _brand.yml file. You have fine-grained control over things like font family, size, weight, and color for different elements of your document, from the base text to headings and titles.

1. While being styled as headings, title and subtitle have a separate implementation.

Logo

The Typst implementation allows customization of the logo position at the document level:

---
format:
  typst:
    logo:
      width: 1in
      location: right-top
      padding-right: 0.5in
      padding-top: 0.25in
      alt: Alternate alternate text
---

The Typst implementation also allows you to customize your document’s logo. You can set its width, location on the page, and padding, giving you complete control over how your branding is displayed.

Your turn

• In your document’s YAML header, change the format option from its current value (e.g., html) to typst.
• Change the number of columns used for the page content to 2 using columns.
• Add a block to a section of the text and fill it with the tertiary color.

05:00

Customizing templates

For even more advanced customization, Typst allows you to define your own custom templates. This lets you create highly specific document types, from academic papers to posters and letters.

Custom Typst formats

Typst allows you to define your own templates to produce highly customized documents.

IEEE

Poster

Letter

Dept News

You can find a bunch of ready-made templates on Quarto’s GitHub page. You can easily use them with the quarto use template command.

Custom Typst formats

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

Here’s a list of some of the custom formats available and how to use them with Quarto. These templates can save you a lot of time by providing a pre-defined structure and style for common document types.

Creating a new Typst format

Use the quarto create command to get started:

Terminal

$ quarto create extension format

Choose typst as the base format and provide a name for the extension.

If you can’t find a template that fits your needs, you can create your own. The quarto create extension format command gives you a starter pack of files to begin with.

Creating a new Typst format

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).

When you create a new format, you get a few key files. The most important ones for our purposes are typst-show.typ and typst-template.typ. typst-show.typ: This file acts as a bridge. It takes the metadata from your Quarto document’s YAML and passes it as arguments to your Typst template function. typst-template.typ: This is the core of your format. It defines the layout and styling of your document.

typst-show.typ

./_extensions/article/typst-show.typ

// Typst custom formats typically consist of a 'typst-template.typ' (which is
// the source code for a typst template) and a 'typst-show.typ' which calls the
// template's function (forwarding Pandoc metadata values as required)
//
// This is an example 'typst-show.typ' file (based on the default template  
// that ships with Quarto). It calls the typst function named 'article' which 
// is defined in the 'typst-template.typ' file. 
//
// If you are creating or packaging a custom typst template you will likely
// want to replace this file and 'typst-template.typ' entirely. You can find
// documentation on creating typst templates here and some examples here:
//   - https://typst.app/docs/tutorial/making-a-template/
//   - https://github.com/typst/templates
#show: doc => article(
$if(title)$
  title: [$title$],
$endif$
$if(subtitle)$
  subtitle: [$subtitle$],
$endif$
$if(by-author)$
  authors: (
$for(by-author)$
$if(it.name.literal)$
    ( name: [$it.name.literal$],
      affiliation: [$for(it.affiliations)$$it.name$$sep$, $endfor$],
      email: [$it.email$] ),
$endif$
$endfor$
    ),
$endif$
$if(date)$
  date: [$date$],
$endif$
$if(lang)$
  lang: "$lang$",
$endif$
$if(region)$
  region: "$region$",
$endif$
$if(abstract)$
  abstract: [$abstract$],
  abstract-title: "$labels.abstract$",
$endif$
$if(margin)$
  margin: ($for(margin/pairs)$$margin.key$: $margin.value$,$endfor$),
$endif$
$if(papersize)$
  paper: "$papersize$",
$endif$
$if(mainfont)$
  font: ("$mainfont$",),
$elseif(brand.typography.base.family)$
  font: $brand.typography.base.family$,
$endif$
$if(fontsize)$
  fontsize: $fontsize$,
$elseif(brand.typography.base.size)$
  fontsize: $brand.typography.base.size$,
$endif$
$if(title)$
$if(brand.typography.headings.family)$
  heading-family: $brand.typography.headings.family$,
$endif$
$if(brand.typography.headings.weight)$
  heading-weight: $brand.typography.headings.weight$,
$endif$
$if(brand.typography.headings.style)$
  heading-style: "$brand.typography.headings.style$",
$endif$
$if(brand.typography.headings.color)$
  heading-color: $brand.typography.headings.color$,
$endif$
$if(brand.typography.headings.line-height)$
  heading-line-height: $brand.typography.headings.line-height$,
$endif$
$endif$
$if(section-numbering)$
  sectionnumbering: "$section-numbering$",
$endif$
  pagenumbering: $if(page-numbering)$"$page-numbering$"$else$none$endif$,
$if(toc)$
  toc: $toc$,
$endif$
$if(toc-title)$
  toc_title: [$toc-title$],
$endif$
$if(toc-indent)$
  toc_indent: $toc-indent$,
$endif$
  toc_depth: $toc-depth$,
  cols: $if(columns)$$columns$$else$1$endif$,
  doc,
)

This is what a typical typst-show.typ file looks like. It’s a simple script that grabs values from your Quarto YAML (like title, subtitle, and authors) and then calls the article function defined in our template file, passing those values along.

typst-template.typ

./_extensions/article/typst-template.typ

// This is an example typst template (based on the default template that ships
// with Quarto). It defines a typst function named 'article' which provides
// various customization options. This function is called from the 
// 'typst-show.typ' file (which maps Pandoc metadata function arguments)
//
// If you are creating or packaging a custom typst template you will likely
// want to replace this file and 'typst-show.typ' entirely. You can find 
// documentation on creating typst templates and some examples here: 
//   - https://typst.app/docs/tutorial/making-a-template/
//   - https://github.com/typst/templates


#let article(
  title: none,
  subtitle: none,
  authors: none,
  date: none,
  abstract: none,
  abstract-title: none,
  cols: 1,
  margin: (x: 1.25in, y: 1.25in),
  paper: "us-letter",
  lang: "en",
  region: "US",
  font: "libertinus serif",
  fontsize: 11pt,
  title-size: 1.5em,
  subtitle-size: 1.25em,
  heading-family: "libertinus serif",
  heading-weight: "bold",
  heading-style: "normal",
  heading-color: black,
  heading-line-height: 0.65em,
  sectionnumbering: none,
  pagenumbering: "1",
  toc: false,
  toc_title: none,
  toc_depth: none,
  toc_indent: 1.5em,
  doc,
) = {
  set page(
    paper: paper,
    margin: margin,
    numbering: pagenumbering,
  )
  set par(justify: true)
  set text(lang: lang,
           region: region,
           font: font,
           size: fontsize)
  set heading(numbering: sectionnumbering)
  if title != none {
    align(center)[#block(inset: 2em)[
      #set par(leading: heading-line-height)
      #if (heading-family != none or heading-weight != "bold" or heading-style != "normal"
           or heading-color != black) {
        set text(font: heading-family, weight: heading-weight, style: heading-style, fill: heading-color)
        text(size: title-size)[#title]
        if subtitle != none {
          parbreak()
          text(size: subtitle-size)[#subtitle]
        }
      } else {
        text(weight: "bold", size: title-size)[#title]
        if subtitle != none {
          parbreak()
          text(weight: "bold", size: subtitle-size)[#subtitle]
        }
      }
    ]]
  }

  if authors != none {
    let count = authors.len()
    let ncols = calc.min(count, 3)
    grid(
      columns: (1fr,) * ncols,
      row-gutter: 1.5em,
      ..authors.map(author =>
          align(center)[
            #author.name \
            #author.affiliation \
            #author.email
          ]
      )
    )
  }

  if date != none {
    align(center)[#block(inset: 1em)[
      #date
    ]]
  }

  if abstract != none {
    block(inset: 2em)[
    #text(weight: "semibold")[#abstract-title] #h(1em) #abstract
    ]
  }

  if toc {
    let title = if toc_title == none {
      auto
    } else {
      toc_title
    }
    block(above: 0em, below: 2em)[
    #outline(
      title: toc_title,
      depth: toc_depth,
      indent: toc_indent
    );
    ]
  }

  if cols == 1 {
    doc
  } else {
    columns(cols, doc)
  }
}

#set table(
  inset: 6pt,
  stroke: none
)

The typst-template.typ file defines the actual appearance of the document. Here, we define the article function that receives the metadata from typst-show.typ. This function sets the page layout, fonts, and other stylistic elements. For example, the highlighted code shows how the function sets the page’s paper size, margins, and number of columns based on the values it receives. This is where you can get really creative with your designs.

Recreating the World Happiness Report

World Happiness Report example

Let’s look at a more complex example. We’ll try to recreate the styling of the World Happiness Report PDF. This report has a very specific style: a unique cover page, a two-column layout, and custom fonts and colors. We’ll explore how to achieve this with Typst.

Example report with brand.yml

Using just the _brand.yml file, we can get a good start. We can handle things like the table of contents, basic heading styles, and logo placement. However, some elements, like the title page and more advanced heading styles, require a bit more work.

Advanced styling

With brand.yml:

✅ Table of contents

✅ Simple heading styling

✅ Logo placement customization

✅ Fonts

❌ Cover page

❌ Advanced headings

Adding a title page with image

Set rules:

typst-template.typ

#let title_page(title)={
    page(margin: 0in,
        background: image("cover.jpg", height: 100%, fit: "cover"))[
        #set text(fill: white)

        #place(center + horizon, dy: -2.5in)[
            #set align(center + horizon)
            #block(width: 100%, fill: rgb("#983e91"), outset: 5em)[
                #text(weight: "light", size: 36pt, title)
            ]
        ]
        #place(center + bottom, dy: -40pt)[
          #block(height: 40pt)[
            #image("whr_logo.png")
          ]
        ]
    ]
}

To create a custom title page, we can define a function in our typst-template.typ file. This function can set specific page properties, like a background image, and then overlay text and other elements. In this example, we’re using a background image, setting the text color to white, and then placing the title and logo at specific positions. The result is a highly customized title page that perfectly matches the original report’s design.

Your turn

Install the whr-typst-template:

Terminal

quarto use template ivelasq/whr-typst-template

Open the _extensions/whr/typst-show.typ and _extensions/whr/typst-template.typ files to examine their contents.

05:00