= Apply a Theme

After creating a theme, you'll need to tell Asciidoctor PDF where to find it.
This is done using AsciiDoc attributes.

== Theme and font directories

There are three AsciiDoc attributes that tell Asciidoctor PDF how to locate and apply your theme.

pdf-theme:: The name of the YAML theme file to load.
If the name ends with `.yml`, it's assumed to be the complete name of a file and is resolved relative to `pdf-themesdir`, if specified, otherwise the current directory.
Otherwise, `-theme.yml` is appended to the name to make the file name (i.e., `<name>-theme.yml`) and is resolved relative to `pdf-themesdir`, if specified, otherwise the built-in themes dir.

pdf-themesdir:: The directory where the theme file is located.
If the path is relative, the value is resolved starting from the current working directory.
You can use the `+{docdir}+` token as the first path segment to create an absolute path starting from the directory of the document.
_Specifying an absolute path is recommended._
+
If you use images in your theme, image paths are resolved relative to this directory.
If `pdf-theme` ends with `.yml`, and `pdf-themesdir` is not specified, then `pdf-themesdir` defaults to the directory of the path specified by `pdf-theme`.

pdf-fontsdir:: The directory or directories where the fonts used by your theme, if any, are located.
Multiple entries must be separated by either a comma or a semicolon.
To reference a file inside a JAR file on the classpath, prefix with the path with `uri:classloader:` (AsciidoctorJ only).
If the path is relative, the value is resolved starting from the current working directory.
You can use the `+{docdir}+` token as the first path segment to create an absolute path starting from the directory of the document.
_Specifying an absolute path is recommended._

== Load a theme

Let's assume that you've put your theme files inside a directory named `resources` with the following layout:

....
document.adoc
resources/
  themes/
    basic-theme.yml
  fonts/
    roboto-normal.ttf
    roboto-italic.ttf
    roboto-bold.ttf
    roboto-bold_italic.ttf
....

Here's how you'd load your theme when calling Asciidoctor PDF:

 $ asciidoctor-pdf -a pdf-themesdir=resources/themes -a pdf-theme=basic -a pdf-fontsdir=resources/fonts

If all goes well, Asciidoctor PDF should run without an error or warning.

NOTE: You only need to specify the `pdf-fontsdir` if you're using custom fonts in your theme.

You can skip setting the `pdf-themesdir` attribute and just pass the absolute path of your theme file to the `pdf-theme` attribute.

 $ asciidoctor-pdf -a pdf-theme=resources/themes/basic-theme.yml -a pdf-fontsdir=resources/fonts

However, in this case, image paths in your theme won't be resolved properly.

Paths are resolved relative to the current directory.
However, in the future, this may change so that paths are resolved relative to the base directory (typically the document's directory).
Therefore, it's recommended that you specify absolute paths for now to future-proof your configuration.

 $ asciidoctor-pdf -a pdf-themesdir=/path/to/resources/themes -a pdf-theme=basic -a pdf-fontsdir=/path/to/resources/fonts

== Using Maven and Gradle

As usual, you can also use build tools like Maven and Gradle to build a themed PDF.
The only thing you need to add to an existing build is the attributes mentioned above.

* https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-with-theme-example[Maven Example^]
* https://github.com/asciidoctor/asciidoctor-gradle-examples/tree/master/asciidoc-to-pdf-with-theme-example[Gradle Example^]

Speaking of Java, you can bundle and distribute your theme and fonts in a jar file.
To reference the theme file and/or directory of fonts from inside the jar, refer to their location on the classpath using the `uri:classloader:` prefix.
Here's how you'd load both the theme and fonts from the classpath:

 $ asciidoctorj -b pdf -a pdf-theme="uri:classloader:/path/to/themes/my-theme.yml" -a pdf-fontsdir="uri:classloader:/path/to/fonts" document.adoc

This only works when running Asciidoctor PDF on the JVM.