# 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.

Note:
The examples provided here are all in YAML format, which is generally more compact and readable than JSON.

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.

Tip:
For an overview of the elements and other settings that the theme plug-in supports, see Styles, Page settings, Header and footer, and Variables.

## 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 `$brand-color-primary`.

Figure 1. Color variables in dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml

    brand:
      color:
        inverse: '#e9ecef'
        links: '#3563ab'
        note:
          background:
            attention: '#fff3cd'
            caution: '#f8d7da'
            info: '#dce4f0'
            tip: '#d1e7dd'
        primary: '#1d365d'
        secondary: '#6c757d'
        tertiary: '#bac8d1'
        xml-domain: '#639'

The primary and secondary brand colors defined above are used in the examples below under Setting up headers and footers and Adding an image to the cover page. The theme sample also defines custom brand colors for links, note backgrounds, and XML domain markup.

## 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 style keys.

Figure 2. Font families in dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml

    pdf2:
      font:
        monospaced: 'Courier New, Courier, Arial Unicode MS, Tahoma, Batang, SimSun'
        sans: 'Helvetica, Arial Unicode MS, Tahoma, Batang, SimSun'
        serif: 'Times New Roman, Times, Arial Unicode MS, Tahoma, Batang, SimSun'

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 `$company-font-sans`.

## Defining page sizes

Page settings include page `size`, `orientation`, and margins.

Figure 3. Page settings in dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml

    page:
      mirror-margins: true
      size: PA4

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.

The `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

You can 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.

Figure 4. Switching page size to A4 with dita-ot-dir/docsrc/samples/themes/dita-ot-docs_A4.yaml

    # Sample PDF theme that changes page size for printing on A4 paper
    extends: ./dita-ot-docs-theme.yaml
    page:
      size: A4

Figure 5. Switching page size to Letter with dita-ot-dir/docsrc/samples/themes/dita-ot-docs_Letter.yaml

    # Sample PDF theme that changes page size for printing on US Letter paper
    extends: ./dita-ot-docs-theme.yaml
    page:
      size: 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.

## Setting up headers and footers

The documentation theme includes sample customizations to adjust the content of the running headers and footers that appear on each page.

Figure 6. Formatting headers and running content in dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml

    header:
      color: $brand-color-secondary
      display-align: before
      end-indent: 10mm
      even:
        content: '{part-title}'
        text-align: start
      font-family: $pdf2-font-sans
      odd:
        content: '{chapter-title}'
        text-align: end
      padding-after: 6pt
      padding-before: 12pt
      start-indent: 10mm

These settings use the secondary brand color for page headers (as defined above under Setting custom colors), the sans-serif font families defined above under Defining custom font stacks, and position the content with indentation and padding.

Figure 7. Formatting footers and page numbers in dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml

    footer:
      color: $brand-color-secondary
      end-indent: 10mm
      even:
        content: '{folio}'
        font-weight: bold
        text-align: start
      font-family: $pdf2-font-sans
      odd:
        content: '{folio}'
        font-weight: bold
        text-align: end
      padding-after: 12pt
      padding-before: 6pt
      start-indent: 10mm

These settings use the `{folio}` field to place the current page number on the outside edges of each page footer. The `content` key may include combinations of static text, or reference variables using curly braces. For details on the available options, see Header and footer and Variables.

## Adding an image to the cover page

The `cover` and `cover-title` Styles can be used to add a background image and adjust the formatting and placement of the document title.

Figure 8. Cover page settings in dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml

    cover:
      background-image: dita-ot-logo-inverse.svg
      background-repeat: no-repeat
      height: 25.7cm
    cover-title:
      color: $brand-color-primary
      font-size: 36pt
      font-weight: bold
      line-height: 1.5
      space-before: 195mm

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 setting the `space-before` property for the `cover-title`.

Tip:
The latest version of the documentation theme is available on GitHub: dita-ot-docs-theme.yaml.