1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
= Font Category Keys
:description: Reference list of the available font category keys and their value types.
:navtitle: Font
:source-language: yaml
== 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-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.
[cols="3,3,6a"]
|===
|Key |Value Type |Example
|catalog
|Map
|[source]
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
|[source]
font:
fallbacks:
- M+ 1p Fallback
- Noto Emoji
|===
[#extend-catalog]
== Extending the font catalog
If you define a xref:custom-font.adoc[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
[,yaml]
----
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
[,yaml]
----
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
[,yaml]
----
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.
|
