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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
= Keys, Properties and Values
The Asciidoctor PDF theme language is described using the http://en.wikipedia.org/wiki/YAML[YAML^] data format.
YAML is a human-friendly data format that resembles CSS.
*Note, however, that the theming system isn't actually CSS.*
A theme is stored in a dedicated theme file and described as YAML key-value pairs that can be nested and stored in a dedicated theme file.
The theme language adds some extra features to YAML, such as variables, basic math, measurements, and color values.
[#key-names]
== Key names
//Keys as selectors and properties
The theming language's built-in key names are assembled from selectors and properties.
Selectors are the component you want to style.
The properties are the style elements of that component that can be styled.
All selector names are implicit (e.g., `heading`), so you customize the theme primarily by manipulating pre-defined property values (e.g., `font-size`).
[#css-properties]
=== CSS Properties
The theme language in Asciidoctor PDF supports a limited subset of the properties from CSS.
Some of these properties have different names from those found in CSS.
* An underscore (`_`) may be used in place of a hyphen (`-`) in all property names (so you may use `font_family` or `font-family`).
* An underscore (`_`) may be used in place of a hyphen (`-`) in all variable names (so you may use `$base_font_family` or `$base-font-family`).
* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font-style` key.
See the xref:text.adoc#font-style[Font style section] for allowed values.
* The `align` key in the theme language is roughly equivalent to the `align-self` flexbox property in CSS.
See xref:blocks.adoc#align[Alignment for blocks] for more information.
* The `text-align` key in the theme language has the same function as the `text-align` property in CSS.
See xref:text.adoc#text-align[Text alignment] for more information.
* The `font-color` property in the theme language is equivalent to the `color` property in CSS.
TIP: When you look at the bundled themes, you'll see that they use an underscore to separate key names.
The underscore separator is used for bundled themes since it requires no translation and those themes are loaded frequently.
The hyphen is the preferred separator for use in custom themes since it looks clearer.
[#values]
== Key values
The value of a key may be one of the following types:
* String
** Font family name
** Font style
** Alignment
** Color as hex string (e.g., 'ff0000', #ff0000, or '#ff0000')
** Image path
** Enumerated type (where specified)
** Text content (where specified)
* Null (clears any previously assigned value)
** _empty_ (i.e., no value specified)
** null
** ~
* Number (integer or float) with optional fixed units (default unit is points)
* Array
** Color as RGB array (e.g., [51, 51, 51])
** Color as CMYK array (e.g., [50, 100, 0, 0])
** Border width as ends and sides array (e.g., [10, 5])
** Margin as top, right, bottom, and left array (e.g., [1in, 1in, 1in, 1in])
** Padding (e.g., [1in, 1in, 1in, 1in])
* Variable reference (e.g., $base_font_color or $base-font-color)
* Math expression
Keys almost always require a value of a specific type.
The reference page for each xref:keys.adoc[key category] specifies the acceptable values or value types per key.
== Key nesting
Keys may be nested to an arbitrary depth to eliminate redundant prefixes.
Once the theme is loaded, all keys are flattened into a single map of qualified keys.
Nesting is simply a shorthand way of organizing the keys.
In the end, a theme is just a map of key/value pairs.
Nested keys are adjoined to their parent key with an underscore (`_`) or hyphen (`-`).
This means the selector part (e.g., `link`) is combined with the property name (e.g., `font-color`) into a single, qualified key (e.g., `link_font_color` or `link-font-color`).
For example, let's assume we want to set the base (i.e., global) font size and color.
These keys may be written longhand:
[,yaml]
----
base-font-color: #333333
base-font-family: Times-Roman
base-font-size: 12
----
Or, to avoid having to type the prefix `base-` multiple times, the keys may be written as a hierarchy:
[,yaml]
----
base:
font-color: #333333
font-family: Times-Roman
font-size: 12
----
Or even:
[,yaml]
----
base:
font:
color: #333333
family: Times-Roman
size: 12
----
Each level of nesting must be indented by two spaces from the indentation of the parent level.
Also note the presence of the colon (`:`) after each key name.
== Inheritance
Like CSS, inheritance is a principal feature in the Asciidoctor PDF theme language.
For many of the properties, if a key is not specified, the key inherits the value applied to the parent content in the content hierarchy.
This behavior saves you from having to specify properties unless you want to override the inherited value.
The following keys are inherited:
* `font-family`
* `font-color`
* `font-size`
* `font-style`
* `text-transform`
* `line-height` (some exceptions)
* `margin-bottom` (if not specified, defaults to `$vertical-spacing`)
=== Heading inheritance
Headings inherit starting from a specific heading level (e.g., `heading-h2-font-size`), then to the heading category (e.g., `heading-font-size`), then directly to the base value (e.g., `base-font-size`).
Any setting from an enclosing context, such as a sidebar, is skipped.
|
