Create a Theme

There are two ways to create a PDF theme. One way is to extend one of the built-in themes and gradually layer your customizations over it. The other way is to develop a theme from scratch. There are advantages to both approaches.

Extend the default theme

One theme can extend another theme using the extends key at the top of the theme file. When extending a theme, you only have to define the keys you want to override from the theme you’re extending, which is loaded prior to loading the keys in your theme. Thus, the quickest and simplest way to create a theme is to extend the default theme.

Let’s try this out by drastically modifying the base font color. That way, you can clearly tell when Asciidoctor PDF is using your theme. Create a new file named my-theme.yml and populate it with the following code:

my-theme.yml
extends: default
base:
  font-color: #FF0000

This approach is useful if you want to modify the behavior of the converter or the running content without otherwise changing the style. For example, here’s a theme that customizes the text in the running footer.

extends: default
footer:
  recto:
    right:
      content: A recto page
  verso:
    left:
      content: A verso page

Learn more about how to customize the running content on the Add Running Content page.

How the extends key works

The extends key accepts either a single value or an array of values. Each value is interpreted as either a theme name or filename.

If the value matches the name of a built-in theme (e.g., default), that theme is used. If the value is an absolute path, that theme file is used. If the value begins with ./, the value is resolved to a theme file relative to the current theme file. Otherwise, the value is resolved just like the value of the pdf-theme attribute. In this case, a relative path is resolved starting from the value of the pdf-themesdir attribute.

If the same theme appears multiple times in the theme hierarchy, it will only be loaded once by default. You can force the theme to be loaded, even if it has already been loaded, by adding the !important keyword at the end of the value offset by a space.

Initially, the theme starts out empty. Then, the theme file(s) referenced by the extends key are loaded in order. Finally, the keys in the current file are loaded. Each time a theme is loaded, the flattened keys are overlaid onto the keys from the previous theme.

If you don’t want to extend any theme (not even the base theme), omit the extends key or assign the value ~ to the extends key.

Extend the base theme

If you’re trying to carefully tailor the appearance of the PDF, you might find that the default theme gets in the way too much. In this case, it might be better to extend the base theme.

The base theme provides rudimentary styling so that the visual hierarchy and block and inline elements of the content are honored, but does very little to embellish it.

If you extend the base theme or create a theme from scratch, we strongly recommend defining TrueType fonts and specifying them in the base and codespan categories. Otherwise, Asciidoctor PDF will use built-in AFM fonts, which can result in missing functionality and warnings.

Here’s an example of a theme that extends the base theme:

my-theme.yml
extends: base
page:
  layout: portrait
  margin: [0.75in, 1in, 0.75in, 1in]
  size: Letter
base:
  font-color: #333333
  font-family: Times-Roman
  font-size: 12
  line-height-length: 17
  line-height: $base-line-height-length / $base-font-size
role:
  removed:
    font-style: italic
    text-decoration: line-through
    text-decoration-color: #FF0000
heading:
  font-color: #262626
  font-size: 17
  font-style: bold
  line-height: 1.2
  margin-bottom: 10
link:
  font-color: #002FA7
list:
  indent: $base-font-size * 1.5

If you want to go even more barebones, then you can set the extends key to ~ (or omit it) so the converter does not load any theme before your own.

my-theme.yml
extends: ~
#...

If you do this, you should consult the base theme to discover which keys you’ll need to set to support the visual hierarchy and core block and inline elements. You can also find the location of the data/themes directory on your local disk by running the following command:

$ gem contents asciidoctor-pdf --show-install-dir