Font Category Keys

font

The font category key is where you declare custom fonts (catalog key) and configure the fallback fonts (fallbacks key).

The data format of the catalog key is a map. Each key is the name of the font that you can use to refer to the font elsewhere in the theme. The value is either a font path (which is used for all font styles) or another map that specifies a font path to each of the four font styles. You can also configure the catalog to merge entries from an inherited font catalog. See Extend the font catalog.

The data format of the fallbacks key is an array. The values of the array are the font names declared in the catalog (or a name inherited from another theme). These fallbacks are used, in the order listed, when a glyph cannot be found in the primary font for a given element.

Key Value Type Example

catalog

Map

font:
  catalog:
    Noto Sans:
      normal: GEM_FONTS_DIR/notosans-regular-subset.ttf
      bold: GEM_FONTS_DIR/notosans-bold-subset.ttf
      italic: GEM_FONTS_DIR/notosans-italic-subset.ttf
      bold_italic: GEM_FONTS_DIR/notosans-bold_italic-subset.ttf

fallbacks

Array

font:
  fallbacks:
  - M+ 1p Fallback
  - Noto Emoji

Extend the font catalog

If you define a custom font in the font catalog in a theme that extends from default, and you want to continue to use the bundled fonts in your theme, you either have to redeclare the bundled fonts:

Redeclaring the bundle fonts in a custom theme
extends: default
font:
  catalog:
    Noto Serif:
      normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
      bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
      italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
      bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
    M+ 1mn:
      normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
      bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
      italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
      bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
    Your Font:
      normal: /path/to/your/font.ttf
heading:
  font-family: Your Font

or you need to set merge: true above your font definitions:

Merging with the inherited font catalog
extends: default
font:
  catalog:
    merge: true
    Your Font:
      normal: /path/to/your/FontName-Regular.ttf
      italic: /path/to/your/FontName-Italic.ttf
      bold: /path/to/your/FontName-Bold.ttf
      bold_italic: /path/to/your/FontName-BoldItalic.ttf
heading:
  font-family: Your Font

If you want to refer to a bundled font in your font catalog, you need to prefix the path with GEM_FONTS_DIR (or add GEM_FONTS_DIR to the value of the pdf-fontsdir attribute) so the converter can find and register it. You can find the bundle font definitions in default theme.

If your font only has a single style, or you want to use the same style for all four font styles, assign the font path directly to the key that declares the font name:

Mapping a single font to all four font styles
extends: default
font:
  catalog:
    merge: true
    Your Font: /path/to/your/FontName-Regular.ttf
heading:
  font-family: Your Font

When not using this shorthand, you must map all four font styles.