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 |
|
fallbacks |
Array |
|
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:
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:
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:
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.