= Customize the Theme
:description: Customize a PDF theme by extending a built-in theme.

[#extend-default]
== Extend the default theme

A theme can extend another theme using the `extends` key.
For example:

[,yaml]
----
extends: default
base:
  font-color: #FF0000
----

The `extends` key accepts either a single value or an array of values.
Each value is interpreted as a filename.
If the filename equals `default`, it resolves to the location of the default (built-in) theme.
If the filename is absolute, it's used as is.
If the filename begins with `./`, it's resolved as a theme file relative to the current theme file.
Otherwise, the filename is resolved as a theme file in the normal way (relative to the value of the `pdf-themesdir` attribute).

Currently, the theme starts out empty.
Then, the files 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 keys are overlaid onto the keys from the previous theme.

== Basic theme

Here's an example of a basic theme file that extends the base theme:

.basic-theme.yml
[,yaml]
----
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
footer:
  height: $base-line-height-length * 2.5
  line-height: 1
  recto:
    right:
      content: '{page-number}'
  verso:
    left:
      content: $footer-recto-right-content
----

When creating a new theme, you only have to define the keys you want to override from the extended theme, which is loaded prior to loading your custom theme.
The converter uses the information from the theme map to help construct the PDF.

== Basic extended theme

Instead of designing a theme from scratch, you can extend the default theme using the `extends` key as follows:

[,yaml]
----
extends: default
base:
  font-color: #FF0000
----

You can also point the `extends` key at another custom theme to extend from it.
If you don't want to extend any theme, including the base theme, omit the `extends` key or assign the value `~` to the `extends` key (i.e., `extends: ~`).

[#load-theme-more-than-once]
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.

WARNING: If you start a new 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.

[TIP]
====
Instead of creating a theme from scratch, another option is to download the {url-repo-root}/data/themes/default-theme.yml[default-theme.yml^] file from the source repository.
Save the file using a unique name (e.g., _custom-theme.yml_) and start hacking on it.

Alternatively, you can snag the file from your local installation using the following command:

 $ ASCIIDOCTOR_PDF_DIR=`gem contents asciidoctor-pdf --show-install-dir`;\
   cp "$ASCIIDOCTOR_PDF_DIR/data/themes/default-theme.yml" custom-theme.yml
====