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 or file path of the theme to load.
If the value of the
pdf-theme
attribute ends with.yml
(e.g.,custom-theme.yml
), the name is assumed to be an absolute or relative file path. If the path is relative, it’s resolved starting from the value of thepdf-themesdir
attribute. If thepdf-themesdir
attribute is not specified, the current working directory is used instead.If the value of the
pdf-theme
attribute doesn’t end with.yml
(e.g.,base
), the suffix-theme.yml
is automatically appended to build a valid absolute or relative file path (i.e.,<name>-theme.yml
). If the resulting file path is relative, it’s resolved starting from the value of thepdf-themesdir
attribute. If thepdf-themesdir
is not specified, the built-in themes directory is used instead (rather than the current working directory).You can use the
{docdir}
token as the first path segment in the name to build an absolute path starting from the directory of the source document.Can be specified using the
--theme
CLI option as a shorthand. - 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 build an absolute path starting from the directory of the source document.Relative image paths in your theme are resolved starting from this location. (In the future, these relative paths may be resolved starting from the directory where the theme file is located, which could be different).
- 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.
Load a theme
Let’s assume that you’ve put your theme files inside a directory named resources
with the following layout:
doc.adoc resources/ themes/ basic-theme.yml fonts/ roboto-normal.ttf roboto-italic.ttf roboto-bold.ttf roboto-bold_italic.ttf
Here’s the formal way of loading your theme when calling Asciidoctor PDF:
$ asciidoctor-pdf -a pdf-theme=basic -a pdf-themesdir=resources/themes -a pdf-fontsdir=resources/fonts doc.adoc
You can shorten -a pdf-theme=
to --theme
:
$ asciidoctor-pdf --theme basic -a pdf-themesdir=resources/themes -a pdf-fontsdir=resources/fonts doc.adoc
If all goes well, Asciidoctor PDF will convert your document without any errors or warnings.
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 by passing the relative path of your theme file to the theme
option:
$ asciidoctor-pdf --theme resources/themes/basic-theme.yml -a pdf-fontsdir=resources/fonts doc.adoc
These relative paths are resolved starting from the current working directory.
Alternately, you can use {docdir}
as the first path segment to anchor them to the directory of the source document instead.
If you’re having difficulty getting the converter to locate your theme or fonts, you can specify absolute paths instead, which are used as is.
$ asciidoctor-pdf --theme /path/to/resources/themes/basic-theme.yml -a pdf-fontsdir=/path/to/resources/fonts doc.adoc
Relative font paths in the theme are resolved starting from the directory resolved from the pdf-fontsdir
attribute.
All other paths in the theme are resolved starting from the directory where the theme file is found.
You can prefix paths in the theme using the {docdir}
or {docimagesdir}
attribute references.
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.
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.