= Asciidoctor PDF Theming Guide
Dan Allen <https://github.com/mojavelinux>
:toc: macro
:icons: font
:idprefix:
:idseparator: -
:window: _blank

////
Topics remaining to document:
* line height and line height length (and what that all means)
* title page layout / title page images (logo & background)
* document that unicode escape sequences can be used inside double-quoted strings
////

The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file that Asciidoctor PDF generates from AsciiDoc.
The theme is driven by a YAML-based configuration file.
This document explains how the theming system works, how to define a custom theme and how to enable the theme when running Asciidoctor PDF.

toc::[]

== Language overview

The theme language in Asciidoctor PDF is based on the http://en.wikipedia.org/wiki/YAML[YAML] data format and incorporates many concepts from CSS and SASS.
Therefore, if you have a background in web design, the theme language should be immediately familiar to you.

Like CSS, themes have both selectors and properties.
Selectors are the component you want to style.
The properties are the style elements of that component that can be styled.
All selector names are implicit (e.g., `heading`), so you customize the theme primarily by manipulating pre-defined property values (e.g., `font_size`).

[NOTE]
====
The theme language in Asciidoctor PDF supports a limited subset of the properties from CSS.
Some of these properties have different names from those found in CSS.

Instead of separate properties for font weight and font style, the theme language combines these as the `font_style` property (allowing values "normal", "bold", "italic" and "bold_italic").

The `text_align` property from CSS is the `align` property in the theme language.

The `color` property from CSS is the `font_color` property in the theme language.
====

A theme (or style) is described in a YAML-based data format and stored in a dedicated theme file.
YAML is a human-friendly data format that resembles CSS and helps to describe the theme.
The theme language adds some extra features to YAML, such as variables, basic math, measurements and color values.
These enhancements will be explained in detail in later sections.

The theme file must be named _<name>-theme.yml_, where `<name>` is the name of the theme.

Here's an example of a basic theme file:

.basic-theme.yml
[source,yaml]
----
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
vertical_rhythm: $base_line_height_length
heading:
  font_color: #262626
  font_size: 17
  font_style: bold
  line_height: 1.2
  margin_bottom: $vertical_rhythm
link:
  font_color: #002FA7
outline_list:
  indent: $base_font_size * 1.5
----

When creating a new theme, you only have to define the keys you want to override from the base theme (PENDING, see https://github.com/asciidoctor/asciidoctor-pdf/issues/132[#132]).
The converter uses the information from the theme map to help construct the PDF.
All the available keys are documented in <<keys>>.

Keys may be nested to an arbitrary depth to eliminate redundant prefixes (an approach inspired by SASS).
Once the theme is loaded, all keys are flattened into a single map of qualified keys.
Nesting is simply a shorthand way of organizing the keys.
In the end, a theme is just a map of key/value pairs.

Nested keys are adjoined to their parent key with an underscore (`_`).
This means the selector part (e.g., `link`) is combined with the property name (e.g., `font_color`) into a single, qualified key (e.g., `link_font_color`).

For example, let's assume we want to set the base (i.e., global) font size and color.
These keys may be written longhand:

[source,yaml]
----
base_font_color: #333333
base_font_family: Times-Roman
base_font_size: 12
----

Or, to avoid having to type the prefix `base_` multiple times, the keys may be written hierarchically:

[source,yaml]
----
base:
  font_color: #333333
  font_family: Times-Roman
  font_size: 12
----

Or even:

[source,yaml]
----
base:
  font:
    color: #333333
    family: Times-Roman
    size: 12
----

Each level of nesting must be indented by twice the amount of indentation of the parent level.
Also note the placement of the colon after each key name.

== Values

The value of a key may be one of the following types:

* String
  - Font family name (e.g., Roboto)
  - Font style (normal, bold, italic, bold_italic)
  - Alignment (left, center, right, justify)
  - Color as hex string (e.g., #ffffff)
  - Image path
* Number (integer or float) with optional units (default unit is points)
* Array
  - Color as RGB array (e.g., [51, 51, 51])
  - Color CMYK array (e.g., [50, 100, 0, 0])
  - Margin (e.g., [1in, 1in, 1in, 1in])
  - Padding (e.g., [1in, 1in, 1in, 1in])
* Variable reference (e.g., $base_font_color)
* Math expression

Note that keys almost always require a value of a specific type, as documented in <<keys>>.

=== Inheritance

Like CSS, inheritance is a key feature in the Asciidoctor PDF theme language.
For many of the properties, if a key is not specified, the key inherits the value applied to the parent content in the content hierarchy.
This behavior saves you from having to specify properties unless you want to override the inherited value.

The following keys are inherited:

* font_family
* font_color
* font_size
* font_style
* line_height (currently some exceptions)
* text_transform (only for headings)
* margin_bottom (falls back to $vertical_rhythm)

.Heading Inheritance
****
Headings are special in that they inherit starting from a specific heading level (e.g., `heading_font_size_h2`) to the heading category (e.g., `heading_font_size`) and then directly to the base value (e.g., `base_font_size`), skipping any enclosing context.
****

=== Variables

To save you from having to type the same value in your theme over and over, or to allow you to base one value on another, the theme language supports variables.
Variables consist of the key name preceded by a dollar (`$`) (e.g., `$base_font_size`).
Any qualified key that has already been defined can be referenced in the value of another key.
(In order words, as soon as the key is assigned, it's available to be used as a variable).

For example, once the following line is processed,

[source,yaml]
----
base:
  font_color: #333333
----

the variable `$base_font_color` will be available for use in subsequent lines and will resolve to `#333333`.

Let's say you want to make the font color of the sidebar title the same as the heading font color.
Just assign the value `$heading_font_color` to the `$sidebar_title_font_color`.

[source,yaml]
----
heading:
  font_color: #191919
sidebar:
  title:
    font_color: $heading_font_color
----

You can also use variables in math expressions to use one value to build another.
This is commonly done to set font sizes proportionally.
It also makes it easy to test different values very quickly.

[source,yaml]
----
base:
  font_size: 12
  font_size_large: $base_font_size * 1.25
  font_size_small: $base_font_size * 0.85
----

We'll cover more about math expressions later.

==== Custom variables

You can define arbitrary key names to make custom variables.
This is one way to group reusable values at the top of your theme file.
If you are going to do this, it's recommended that you organize the keys under a custom namespace, such as `brand`.

For instance, here's how you can define your (very patriotic) brand colors:

[source,yaml]
----
brand:
  red: #E0162B
  white: #FFFFFF
  blue: #0052A5
----

You can now use these custom variables later in the theme file:

[source,yaml]
----
base:
  font_color: $brand_blue
----

=== Math expressions & functions

The theme language supports basic math operations to support calculated values.
The following table lists the supported operations and the corresponding operator for each.

[%header%autowidth]
|===
|Operation |Operator

|multiply
|*

|divide
|/

|add
|+

|subtract
|-
|===

NOTE: Like programming languages, multiple and divide take precedence over add and subtract.

The operator must always be surrounded by a space on either side.
Here's an example of a math expression with fixed values.

[source,yaml]
----
conum:
  line_height: 4 / 3
----

Variables may be used in place of numbers anywhere in the expression:

[source,yaml]
----
base:
  font_size: 12
  font_size_large: $base_font_size * 1.25
----

Values used in a math expression are automatically coerced to a float value before the operation.
If the result of the expression is an integer, the value is coerced to an integer afterwards.

IMPORTANT: Numeric values less than 1 must have a 0 before the decimal point (e.g., 0.85).

The theme language also supports several functions for rounding the result of a math expression.
The following functions may be used if they surround the whole value or expression for a key.

round(...):: Rounds the number to the nearest half integer.
floor(...):: Rounds the number up to the next integer.
ceil(...):: Rounds the number down the previous integer.

You might use these functions in font size calculations so that you get more exact values.

[source,yaml]
----
base:
  font_size: 12.5
  font_size_large: ceil($base_font_size * 1.25)
----

=== Measurement units

Several of the keys require a value in points (pt), the unit of measure for the PDF canvas.
A point is defined as 1/72 of an inch.
However, us humans like to think in real world units like inches (in), centimeters (cm) or millimeters (mm).
You can let the theme do this conversion for you automatically by adding a unit notation next to any number.

The following units are supported:

[%header%autowidth]
|===
|Unit |Suffix

|Inches
|in

|Centimeter
|cm

|Millimeter
|mm

|Points
|pt
|===

Here's an example of how you can use inches to define the page margins:

[source,yaml]
----
page:
  margin: [0.75in, 1in, 0.75in, 1in]
----

The order of elements in a measurement array is the same as it is in CSS:

. top
. right
. bottom
. left

=== Colors

The theme language supports color values in three formats:

Hex:: A string of 3 or 6 characters with an optional leading `#`.
+
The special value `transparent` indicates that a color should not be used.
RGB:: An array of numeric values ranging from 0 to 255.
CMYK:: An array of numeric values ranging from 0 to 1 or from 0% to 100%.

==== Hex

The hex color value is likely most familiar to web developers.
The value must be either 3 or 6 characters (case insensitive) with an optional leading hash (`#`).

The following are all equivalent values for the color red:

[%autowidth,cols=4]
|===
|f00
|#f00
|ff0000
|#ff0000
|F00
|#F00
|FF0000
|#FF0000
|===

Here's how a hex color value appears in the theme file:

[source,yaml]
----
base:
  font_color: #ff0000
----

It's also possible to specify no color by assigning the special value `transparent` as shown here:

[source,yaml]
----
base:
  background_color: transparent
----

==== RGB

An RGB array value must be three numbers ranging from 0 to 255.
The values must be separated by commas and be surrounded by square brackets.

NOTE: An RGB array is automatically converted to a hex string internally, so there's no difference between ff0000 and [255, 0, 0].

Here's how to specify the color red in RGB:

* [255, 0, 0]

Here's how a RGB color value appears in the theme file:

[source,yaml]
----
base:
  font_color: [255, 0, 0]
----

==== CMYK

A CMYK array value must be four numbers ranging from 0 and 1 or from 0% to 100%.
The values must be separated by commas and be surrounded by square brackets.

Unlike the RGB array, the CMYK array _is not_ converted to a hex string internally.
PDF has native support for CMYK colors, so you can preserve the original color values in the final PDF.

Here's how to specify the color red in CMYK:

* [0, 0.99, 1, 0]
* [0, 99%, 100%, 0]

Here's how a CMYK color value appears in the theme file:

[source,yaml]
----
base:
  font_color: [0, 0.99, 1, 0]
----

=== Images

An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax.
Images are currently resolved relative to the value of the `pdf-stylesdir` attribute.

The following image types (and corresponding file extensions) are supported:

* PNG (.png)
* JPEG (.jpg)
* SVG (.svg)

CAUTION: The GIF format (.gif) is not supported.

Here's how an image is specified in the theme file as a bare image path:

[source,yaml]
----
title_page:
  background_image: title-cover.png
----

Here's how the image is specified using the inline image macro:

[source,yaml]
----
title_page:
  background_image: image:title-cover.png[]
----

Like in the AsciiDoc syntax, the inline image macro allows you to supply set the width of the image and the alignment:

[source,yaml]
----
title_page:
  logo_image: image:logo.png[width=250,align=center] 
----

== Fonts

You can select from <<built-in-fonts,built-in PDF fonts>>, <<bundled-fonts,fonts bundled with Asciidoctor PDF>> or <<custom-fonts,custom fonts>> loaded from TrueType font (TTF) files.
If you want to use custom fonts, you must first declare them in your theme file.

=== Built-in fonts

The names of the built-in fonts (for general-purpose text) are as follows:

[%header%autowidth]
|===
|Font Name |Font Family

|Helvetica
|sans-serif

|Times-Roman
|serif

|Courier
|monospace
|===

Using a built-in font requires no additional files.
You can use the key anywhere a `font_family` property is accepted in the theme file.
For example:

[source,yaml]
----
base:
  font_family: Times-Roman
----

However, when you use a built-in font, the characters that you use in your document are limited to the WINANSI (http://en.wikipedia.org/wiki/Windows-1252[Windows-1252]) code set.
WINANSI includes most of the characters needed for writing in Western languages (English, French, Spanish, etc).
For anything outside of that, PDF is BYOF (Bring Your Own Font).

Even though the built-in fonts require the content to be encoded in WINANSI, _you still type your AsciiDoc document in UTF-8_.
Asciidoctor PDF encodes the content into WINANSI when building the PDF.
Any characters in your AsciiDoc document that cannot be encoded will be replaced with an underscore (`_`).

=== Bundled fonts

Asciidoctor PDF bundles several fonts that are used in the default theme.
You can also use these fonts in your custom theme.
These fonts provide more characters than the built-in PDF fonts, but still only a subset of UTF-8.

The family name of the fonts bundled with Asciidoctor PDF are as follows:

http://www.google.com/get/noto/#/family/noto-serif[NotoSerif]::
A serif font that can be styled as normal, italic, bold or bold_italic.

http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1mn[Mplus1mn]::
A monospaced font that maps different thicknesses to the styles normal, italic, bold and bold_italic.
Also provides the circuled numbers used in callouts.

http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1p[Mplus1pMultilingual]::
A sans-serif font that provides a very complete set of Unicode glyphs.
Cannot be styled as italic, bold or bold_italic.
Useful as a fallback font.

CAUTION: At the time of this writing, you cannot use the bundled fonts if you define your own custom fonts.
This limitation may be lifted in the future.

=== Custom fonts

The limited character set of WINANSI, or the bland look of the built-in fonts, may motivate you to load your own font.
Custom fonts can enhance the look of your PDF theme substantially.

To start, you need to find a collection of TTF file of the font you want to use.
A collection typically consists of all four styles of a font:

* normal
* italic
* bold
* bold_italic

You'll need all four styles to support AsciiDoc content properly.
_Asciidoctor PDF cannot italicize a font that is not italic like a browser can._

Once you've obtained the TTF files, put them into a directory in your project where you want to store the fonts.
It's recommended that you name them consistently so it's easier to type the names in the theme file.

Let's assume the name of the font is https://github.com/google/roboto/tree/master/out/RobotoTTF[Roboto].
Name the files as follows:

* roboto-normal.ttf (_originally Roboto-Regular.ttf_)
* roboto-italic.ttf (_originally Roboto-Italic.ttf_)
* roboto-bold.ttf (_originally Roboto-Bold.ttf_)
* roboto-bold_italic.ttf (_originally Roboto-BoldItalic.ttf_)

Next, declare the font under the `font_catalog` key at the top of your theme file, giving it a unique key (e.g., `Roboto`).

[source,yaml]
----
font:
  catalog:
    Roboto:
      normal: roboto-normal.ttf
      italic: roboto-italic.ttf
      bold: roboto-bold.ttf
      bold_italic: roboto-bold_italic.ttf
----

You can use the key you gave to the font in the font catalog anywhere a `font_family` property is accepted in the theme file.
For instance, to use the Roboto font for all headings, you'd use:

[source,yaml]
----
heading:
  font_family: Roboto
----

When you execute Asciidoctor PDF, you need to specify the directory where the fonts reside using the `pdf-fontsdir` attribute:

 $ asciidoctor-pdf -a pdf-style=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc

WARNING: Currently, all fonts referenced by the theme need to be present in the directory specified by the `pdf-fontsdir` attribute.

You can add any number of fonts to the catalog.
Each font must be assigned a unique key, as shown here:

[source,yaml]
----
font:
  catalog:
    Roboto:
      normal: roboto-normal.ttf
      italic: roboto-italic.ttf
      bold: roboto-bold.ttf
      bold_italic: roboto-bold_italic.ttf
    RobotoLight:
      normal: roboto-light-normal.ttf
      italic: roboto-light-italic.ttf
      bold: roboto-light-bold.ttf
      bold_italic: roboto-light-bold_italic.ttf
----

=== Fallback fonts

If one of your fonts is missing a character that is used in a document, such as special symbols, you can tell Asciidoctor PDF to retrieve the character from a fallback font.
You only need to specify one fallback font...typically one that has a full set of symbols.

Like with other custom fonts, you first need to declare the fallback font.
Let's choose https://android.googlesource.com/platform/frameworks/base/+/master/data/fonts/[Droid Sans Fallback].
You can map all the styles to a single font file (since bold and italic don't usually make sense for symbols).

[source,yaml]
----
font:
  catalog:
    Roboto:
      normal: roboto-normal.ttf
      italic: roboto-italic.ttf
      bold: roboto-bold.ttf
      bold_italic: roboto-bold_italic.ttf
    DroidSansFallback:
      normal: droid-sans-fallback.ttf
      italic: droid-sans-fallback.ttf
      bold: droid-sans-fallback.ttf
      bold_italic: droid-sans-fallback.ttf
----

Next, assign the key to the `fallbacks` key under the `font_catalog` key.
Be sure to surround the key name in square brackets as shown below.

[source,yaml]
----
font:
  catalog:
    Roboto:
      normal: roboto-normal.ttf
      italic: roboto-italic.ttf
      bold: roboto-bold.ttf
      bold_italic: roboto-bold_italic.ttf
    DroidSansFallback:
      normal: droid-sans-fallback.ttf
      italic: droid-sans-fallback.ttf
      bold: droid-sans-fallback.ttf
      bold_italic: droid-sans-fallback.ttf
  fallbacks: [DroidSansFallback]
----

TIP: If you are using more than one fallback font, separate each key name by a comma.

That's it!
Now you're covered.
You don't need to reference the fallback font anywhere else in your theme file to use it.

CAUTION: Using a fallback font does slow down PDF generation slightly.
It's best to select fonts that have all the characters you need.

== Keys

TBW

=== Page

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|page_background_color
|<<colors,color>>
|background_color: ffffff

|page_layout
|portrait, landscape
|layout: portrait

|page_margin
|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
|margin: [0.5in, 0.67in, 0.67in, 0.67in]

|page_size
|named size, <<measurement-units,measurement array [width, height]>>
|size: Letter
|===

=== Base

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|base_font_color
|<<colors,color>>
|font_color: #333333

|base_font_family
|<<fonts,font family name>>
|font_family: NotoSerif

|base_font_size
|<<values,number>>
|font_size: 10.5

|base_line_height_length^[1]^
|<<values,number>>
|line_height_length: 12

|base_line_height^[1]^
|<<values,number>>
|line_height: 1.14

|base_font_size_large
|<<values,number>>
|font_size_large: 13

|base_font_size_small
|<<values,number>>
|font_size_small: 9

|base_font_style
|normal, italic, bold, bold_italic
|font_style: normal

|base_align
|left, center, right, justify
|align: justify

|base_border_radius
|<<values,number>>
|border_radius: 4

|base_border_width
|<<values,number>>
|border_width: 0.5

|base_border_color
|<<colors,color>>
|border_color: eee
|===

^[1]^ You should set either `line_height` or `line_height_length` and derive the value of the other using a calculation since these are correlated values.
For instance, if you set `line_height_length`, then use `line_height: $base_line_height_length / $base_font_size` to define the line height.

=== Vertical and horizontal rhythm

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|vertical_rhythm
|<<values,number>>
|vertical_rhythm: 12

|horizontal_rhythm
|<<values,number>>
|horizontal_rhythm: 12
|===

NOTE: Vertical and horizontal rhythm are used for vertical and horizontal spacing, respectively, when there a specific theme key is not defined for a certain purpose.
These keys predated the CSS-style theme system and are planned to be phased out.

=== Link

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|link_font_color
|<<colors,color>>
|font_color: 428BCA

|link_font_family
|<<fonts,font family name>>
|font_family: Roboto

|link_font_size
|<<values,number>>
|font_size: 9

|link_font_style
|normal, italic, bold, bold_italic
|font_style: normal
|===

=== Literal inline

The literal key is used for inline monospaced text in prose and table cells.

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|literal_font_color
|<<colors,color>>
|font_color: B12146

|literal_font_family
|<<fonts,font family name>>
|font_family: Mplus1mn

|literal_font_size
|<<values,number>>
|font_size: 12

|literal_font_style
|normal, italic, bold, bold_italic
|font_style: bold
|===

=== Heading

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|heading_font_color
|<<colors,color>>
|font_color: 333333

|heading_font_family
|<<fonts,font family name>>
|font_family: NotoSerif

|heading_font_size
|<<values,number>>
|font_size: 9

|heading_font_style
|normal, italic, bold, bold_italic
|font_style: bold

|heading_h<n>_font_color^[1]^
|<<colors,color>>
|h2_font_color: [0, 99%, 100%, 0]

|heading_h<n>_font_family^[1]^
|<<fonts,font family name>>
|h4_font_family: Roboto

|heading_h<n>_font_size^[1]^
|<<values,number>>
|h6_font_size: round($base_font_size * 1.7)

|heading_h<n>_font_style^[1]^
|normal, italic, bold, bold_italic
|h3_font_style: bold_italic

|heading_line_height
|<<values,number>>
|line_height: 1.2

|heading_margin_top
|<<measurement-units,measurement>>
|margin_top: $vertical_rhythm * 0.2

|heading_margin_bottom
|<<measurement-units,measurement>>
|margin_bottom: 9.600
|===

^[1]^ `<n>` may be a number ranging from 1 to 6, representing each of the six heading levels.

=== Title page

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|title_page_align
|left, center, right, justify
|align: right

|title_page_title_top
|percentage
|title_top: 55%

|title_page_title_font_size
|<<values,number>>
|title_font_size: 27

|title_page_title_font_color
|<<colors,color>>
|title_font_color: 999999

|title_page_title_line_height
|<<values,number>>
|title_line_height: 0.9

|title_page_subtitle_font_size
|<<values,number>>
|subtitle_font_size: 18

|title_page_subtitle_font_style
|normal, italic, bold, bold_italic
|subtitle_font_style: bold_italic

|title_page_subtitle_line_height
|<<values,number>>
|subtitle_line_height: 1

|title_page_authors_margin_top
|<<measurement-units,measurement>>
|authors_margin_top: 13.125

|title_page_authors_font_size
|<<values,number>>
|authors_font_size: $base_font_size_large

|title_page_authors_font_color
|<<colors,color>>
|authors_font_color: 181818

|title_page_revision_margin_top
|<<measurement-units,measurement>>
|revision_margin_top: 13.125
|===

=== Block

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|block_padding
|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
|padding: [12, 15, 12, 15]

|block_margin_top
|<<measurement-units,measurement>>
|margin_top: 0

|block_margin_bottom
|<<measurement-units,measurement>>
|margin_bottom: 1
|===

Block styles are applied to the following block types:

[cols="1a,1a,1a", grid=none, frame=none]
|===
|
* admonition
* example
* quote
|
* verse
* sidebar
* image
|
* listing
* literal
* table
|===

=== Caption

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|caption_font_color
|<<colors,color>>
|font_color: 333333

|caption_font_family
|<<fonts,font family name>>
|font_family: Mplus1mn

|caption_font_size
|<<values,number>>
|font_size: 11

|caption_font_style
|normal, italic, bold, bold_italic
|font_style: italic

|caption_align
|left, center, right, justify
|align: left

|caption_margin_inside
|<<measurement-units,measurement>>
|margin_inside: 3

|caption_margin_outside
|<<measurement-units,measurement>>
|margin_outside: 0
|===

=== Code

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|code_font_color
|<<colors,color>>
|font_color: 333333

|code_font_family
|<<fonts,font family name>>
|font_family: Mplus1mn

|code_font_size
|<<values,number>>
|font_size: 11

|code_font_style
|normal, italic, bold, bold_italic
|font_style: italic

|code_padding
|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
|padding: 11

|code_line_height
|<<values,number>>
|line_height: 1.25

|code_background_color
|<<colors,color>>
|background_color: F5F5F5

|code_border_color
|<<colors,color>>
|border_color: CCCCCC

|code_border_radius
|<<values,number>>
|border_radius: 4

|code_border_width
|<<values,number>>
|border_width: 0.75
|===

=== Blockquote

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|blockquote_font_color
|<<colors,color>>
|font_color: 333333

|blockquote_font_family
|<<fonts,font family name>>
|font_family: Notoserif

|blockquote_font_size
|<<values,number>>
|font_size: 13

|blockquote_font_style
|normal, italic, bold, bold_italic
|font_style: bold

|blockquote_border_width
|<<values,number>>
|border_width: 5

|blockquote_border_color
|<<colors,color>>
|border_color: EEEEEE

|blockquote_cite_font_size
|<<values,number>>
|cite_font_size: 9

|blockquote_cite_font_color
|<<colors,color>>
|cite_font_color: 999999

|blockquote_cite_font_family
|<<fonts,font family name>>
|cite_font_family: Notoserif

|blockquote_cite_font_style
|normal, italic, bold, bold_italic
|cite_font_style: bold

|===

=== Sidebar

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|sidebar_border_color
|<<colors,color>>
|border_color: FFFFFF

|sidebar_border_radius
|<<values,number>>
|border_radius: 4

|sidebar_border_width
|<<values,number>>
|border_width: 0.5

|sidebar_background_color
|<<colors,color>>
|background_color: EEEEEE

|sidebar_title_font_color
|<<colors,color>>
|title_font_color: 333333

|sidebar_title_font_family
|<<fonts,font family name>>
|title_font_family: NotoSerif

|sidebar_title_font_size
|<<values,number>>
|title_font_size: 13

|sidebar_title_font_style
|normal, italic, bold, bold_italic
|title_font_style: bold

|sidebar_title_align
|left, center, right, justify
|title_align: center
|===

=== Example

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|example_border_color
|<<colors,color>>
|border_color: EEEEEE

|example_border_radius
|<<values,number>>
|border_radius: 4

|example_border_width
|<<values,number>>
|border_width: 0.75

|example_background_color
|<<colors,color>>
|background_color: transparent
|===

=== Admonition

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|admonition_border_color
|<<colors,color>>
|border_color: EEEEEE

|admonition_border_width
|<<values,number>>
|border_width: 0.5
|===

=== Image

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|image_align_default
|left, center, right, justify
|align_default: left
|===

=== Lead

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|lead_font_size
|<<values,number>>
|font_size: 13

|lead_line_height
|<<values,number>>
|line_height: 1.4
|===

=== Abstract

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|abstract_font_color
|<<colors,color>>
|font_color: 5C6266

|abstract_font_size
|<<values,number>>
|font_size: 13

|abstract_line_height
|<<values,number>>
|line_height: 1.4

|abstract_font_style
|normal, italic, bold, bold_italic
|font_style: italic
|===

=== Thematic break

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|thematic_break_border_color
|<<colors,color>>
|border_colorL EEEEEE

|thematic_break_margin_top
|<<measurement-units,measurement>>
|margin_top: 6

|thematic_break_margin_bottom
|<<measurement-units,measurement>>
|margin_bottom: 18
|===

=== Description list

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|description_list_term_font_style
|normal, italic, bold, bold_italic
|term_font_style: italic

|description_list_description_indent
|<<values,number>>
|description_indent: 15
|===


=== Outline list

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|outline_list_indent
|<<measurement-units,measurement>>
|list_indent: 40

|outline_list_item_spacing
|<<measurement-units,measurement>>
|item_spacing: 4
|===

=== Table

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|table_background_color
|<<colors,color>>
|background_color: FFFFFF

|table_even_row_background_color
|<<colors,color>>
|even_row_background_color: F9F9F9

|table_foot_background_color
|<<colors,color>>
|foot_background_color: F0F0F0

|table_border_color
|<<colors,color>>
|border_color: DDDDDD

|table_border_width
|<<values,number>>
|border_width: 0.5

|table_cell_padding
|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
|cell_padding: [3, 3, 6, 3]
|===

[[key-toc]]
=== Table of contents

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|toc_dot_leader_content
|double-quoted string
|dot_leader_content: ". "

|toc_dot_leader_color
|<<colors,color>>
|dot_leader_color: 999999

|toc_font_color
|<<colors,color>>
|font_color: 333333

|toc_h<n>_font_color
|<<colors,color>>
|h3_font_color: 999999

|toc_font_family
|<<fonts,font family name>>
|font_family: NotoSerif

|toc_font_size
|<<values,number>>
|font_size: 9

|toc_font_style
|normal, italic, bold, bold_italic
|font_style: bold

|toc_line_height
|number
|line_height: 1.5

|toc_indent
|<<measurement-units,measurement>>
|indent: 20

|toc_margin_top
|<<measurement-units,measurement>>
|indent: 20
|===

=== Running header & footer

[cols="3,3,5m"]
|===
|Key |Value Type |Example

|header_background_color
|<<colors,color>>
|background_color: EEEEEE

|header_border_color
|<<colors,color>>
|border_color: DDDDDD

|header_border_width
|<<measurement-units,measurement>>
|border_width: 0.25

|header_font_color
|<<colors,color>>
|font_color: 333333

|header_font_family
|<<fonts,font family name>>
|font_family: NotoSerif

|header_font_size
|<<values,number>>
|font_size: 9

|header_font_style
|normal, italic, bold, bold_italic
|font_style: italic

|header_height
|<<measurement-units,measurement>>
|height: 0.75in

|header_padding
|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
|padding: [0, 3, 0, 3]

|header_image_valign
|top, center, bottom, <<measurement-units,measurement>>
|image_valign: 4

|header_valign
|top, center, bottom
|valign: center

|header_<side>_content_<align>^[1]^
|quoted string
|right: '\{page-number}'

|footer_background_color
|<<colors,color>>
|background_color: EEEEEE

|footer_border_color
|<<colors,color>>
|border_color: DDDDDD

|footer_border_width
|<<measurement-units,measurement>>
|border_width: 0.25

|footer_font_color
|<<colors,color>>
|font_color: 333333

|footer_font_family
|<<fonts,font family name>>
|font_family: NotoSerif

|footer_font_size
|<<values,number>>
|font_size: 9

|footer_font_style
|normal, italic, bold, bold_italic
|font_style: italic

|footer_height
|<<measurement-units,measurement>>
|height: 0.75in

|footer_padding
|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
|padding: [0, 3, 0, 3]

|footer_image_valign
|top, center, bottom, <<measurement-units,measurement>>
|image_valign: 4

|footer_valign
|top, center, bottom
|valign: top

|footer_<side>_content_<align>^[1]^
|quoted string
|center: '\{page-number}'
|===

^[1]^ `<side>` can be `recto` (odd pages) or `verso` (even pages).
`<align>` can be `left`, `center` or `right`.

IMPORTANT: You must define a height for the running header or footer, respectively, or it will not be shown.

NOTE: The background color spans the width of the page.
When a background color is specified, the border also spans the width of the page.

==== Implicit attributes

In addition to the document-level attributes defined in the AsciiDoc document, the following attributes are available when defining the content keys in the footer:

* page-count
* page-number
* document-title
* document-subtitle
* chapter-title
* section-title
* section-or-chapter-title

Here's an example that shows how these attributes can be used in the running footer:

[source,yaml]
----
footer:
  height: 0.75in
  recto_content:
    right: '{section-or-chapter-title} | {page-number}'
  verso_content:
    left: '{page-number} | {chapter-title}'
----

==== Images

You can add an image to the running header or footer using the AsciiDoc inline image syntax.
Note that the image must be the whole value for a given position (left, center or right).
It cannot be combined with text.

Here's an example of how to use an image in the running header (which also applies for the footer).

[source,yaml]
----
header:
  height: 0.75in
  image_valign: 2 # <1>
  recto_content:
    center: image:footer-logo.png[width=80]
  verso_content:
    center: $header_recto_content_center
----
<1> You can use the `footer_valign` attribute to slighly nudge the image up or down.

CAUTION: The image must fit in the allotted space for the running header or footer.
Otherwise, you will run into layout issues.
Adjust the width attribute accordingly.

== Applying your theme

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

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

pdf-stylesdir:: The directory where the theme file is located.
_Specifying an absolute path is recommended._
+
If you use images in your theme, image paths are resolved relative to this directory.

pdf-style:: 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.
Otherwise, `-theme.yml` is appended to the name to make the file name (i.e., `<name>-theme.yml`).

pdf-fontsdir:: The directory where the fonts used by your theme, if any, are located.
_Specifying an absolute path is recommended._

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-stylesdir=resources/themes -a pdf-style=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 are using custom fonts in your theme.

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

 $ asciidoctor-pdf -a pdf-style=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 recommend that you specify absolute paths for now to future-proof your configuration.

  $ asciidoctor-pdf -a pdf-stylesdir=/path/to/resources/themes -a pdf-style=basic -a pdf-fontsdir=/path/to/resources/fonts