Sample theme file
Theme files can be written in either JSON or YAML format. The docsrc/samples/themes folder in the DITA-OT installation directory provides several examples.
The YAML theme file used to produce the PDF output for the DITA-OT documentation is included in the installation directory as dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml.
The examples below include excerpts from this theme that show common customizations. You can adapt these examples for your own requirements.
Setting custom colors
Like in CSS or
Sass, you can use
Variables to define brand colors and other shared values, and re-use these them in other
Styles using semantic references such as
Defining custom font stacks
You can also use
Variables to specify a prioritized list of one or more font family names and reference these
values in the
font-family property of other
This theme uses the default font stacks from the default
org.dita.pdf2 plug-in, but the same
approach can be used to define other font families as required by your corporate identity.
The font variables defined here under the
pdf2 prefix could just as well be added to the
brand key, or under a company name prefix and re-used elsewhere with references such as
Defining page sizes
Page settings include page
orientation, and margins.
The DITA-OT documentation theme uses the
PA4 page size, a 21 × 28 cm transitional format
suitable for printing on both A4 and US Letter paper.
mirror-margins key sets up facing pages for double-sided documents, so the margins of the
left page are a mirror image of those on the right.
Extending and overriding themes
extend one theme with another. The samples in the DITA-OT installation
directory include additional theme files that can be used to override the
PA4 page size in the
documentation theme with either A4 or Letter.
When one of these theme extensions is passed to the dita command via the
--theme option, the
page-size value in the extending theme takes
precedence over the original value in dita-ot-docs-theme.yaml.
If you add any new keys to a theme extension, they will be overlaid onto the keys from the extended theme.
Adding an image to the cover page
Styles can be used to add a background image and adjust the formatting and placement of the
The DITA-OT documentation theme references a background image stored in the same folder as the theme file,
and places the title at the bottom of the page by
space-before property for the