Keys, Properties and Values

The Asciidoctor PDF theme language is described using the 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

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

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 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 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 Text alignment for more information.

  • The font-color property in the theme language is equivalent to the color property in CSS.

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.

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 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:

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:

base:
  font-color: #333333
  font-family: Times-Roman
  font-size: 12

Or even:

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.