Syntactic sugar

Theme files can use syntactic sugar to make them easier to read and write. When theme files are read, any shorthand keys are “desugared” to their more verbose equivalents before they are passed to the stylesheet generator.

Content

The authoring format of the content key is a DSL that supports field and variable references mixed with text.

You can reference DITA-OT variables by name by prefixing them with the number sign # and wrapping them in braces { }. For example:

content: '{#copyright} {year} ACME Corporation'

desugars to

content:
  - kind: variable
    value: copyright
  - kind: text
    value: ' '
  - kind: field
    value: year
  - kind: text
    value: ' ACME Corporation'

which would result in a line like this:

© 2022 ACME Corporation

Page dimensions

When page dimensions are defined using the size and orientation keys, they are desugared to width and height keys using a mapping table for known page sizes.

page:
  size: A4

desugars to

page:
  width: 210mm
  height: 297mm

Style keys for header and footer are collected under the odd and even keys.

header:
  color: silver
  odd:
    font-weight: bold

desugars to

header:
  odd:
    font-weight: bold
    color: silver
  even:
    color: silver

Topic titles

Style keys h1, h2, h3, and h4 are desugared to topic, topic-topic, topic-topic-topic, and topic-topic-topic-topic, respectively.

style:
  h2:
    font-weight: bold

desugars to

header:
  topic-topic:
    font-weight: bold