Typst Brand YAML

Overview

Brand YAML allows consistent colors, fonts, and typography across formats and applications.

This document describes some details of the Typst implementation of Brand YAML for Quarto, and provides troubleshooting tips.

In general, Brand YAML properties use CSS conventions, so this feature relies on Typst CSS functionality.

Color

Brand YAML palette and theme colors are available in Typst brand-color, e.g. brand-color.lime or brand-color.primary.

Lighter versions of the colors, suitable as background colors, are available in brand-background-color, e.g. brand-background-color.success.

Typography

Brand YAML is specified for the following elements and Brand YAML properties. Combinations that are not supported are marked NA.

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

The Quarto Typst and HTML implementations of Brand YAML implement all combinations (except size in revealjs).

Many of the NA combinations are possible in Typst, but were removed for compatibility with the spec in 1bd7a48. If any of those are desired, they can be implemented via a Typst raw block or include-in-header; consult that commit for details.

Missing fonts in Typst

When Typst is unable to find the requested font, it will fall back to a default font. In Typst 0.11, shipped with Quarto 1.6, the default font is Linux Libertine; in Typst 0.12, to be shipped with Quarto 1.7, the default is Libertinus Serif.

Typst 0.12 will warn unknown font family in this case.

To tell Typst to not fall back (and not to display fonts it can’t find), you can add

#set text(fallback: false)

to your document.

Typst Brand YAML will automatically download fonts from Google Fonts and cache them in .quarto/typst-font-cache

Then it tells Typst to use this font directory, in addition to any system fonts available to Typst.

In rare cases, there may be ambiguities about a font’s name that will cause Typst not to find the font. To see if a font is available to Typst, run

quarto typst fonts --font-path .quarto/typst-font-cache 2>&1 | grep *fontname*

Unfortunately with Typst 0.11, there is no flag to ignore system fonts, so you’ll need to grep for the font name.

With Typst 0.12, you can run

quarto typst fonts --ignore-system-fonts --font-path .quarto/typst-font-cache/

to list only the fonts downloaded by Quarto. (In either version of Typst, --variants can be helpful for more detail.)

If the font is listed but it still isn’t working, check for variation in the font name. For example, the Sono font can be downloaded from Google Fonts as Sono, but Typst will only accept Sono Extralight Monospace.

β€œBig number” bug

If you encounter issue #11683, with numbers displaying larger than surrounding text in table output, this is happening because none of the text fonts requested by your table package are available, but some of the emoji fonts are.

Please specify an available font to your table package. In the future, Quarto may implement β€œfont stacks” like system-ui and sans-serif in Typst CSS to fix this bug, but currently these are passed through verbatim, and Typst won’t recognize font stacks.

Typography Test coverage

Which kitchen sink test files contain unique tests for a feature/element combination?

For non-unique tests, first file index is listed.

base headings title subtitle monospace-inline monospace-block link
family 1 1 1 1 1 1 R
size 1 NA NA NA 1 1 R
weight 1 1 1 1 1 2 2
style R 1 1 1 R R R
color 1 1 1 1 1 1 1
background-color R R R R 1 1 1
decoration R R R R R R 1
line-height 1 1 1 1 NA 1 NA

Footnotes

  1. While being styled as headings, title and subtitle have a separate implementation.β†©οΈŽ