Asciidoctor PDF Theming Guide

The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file Asciidoctor PDF generates from AsciiDoc. This document describes how the theming system works, how to define a custom theme in YAML and how to activate the theme when running Asciidoctor PDF.

❗	If you’re using a custom theme, you’re expected to override some of keys described in the sections below, in particular fonts. If you don’t define your own fonts, the built-in PDF fonts will be used.

Language overview
Values
Fonts
Keys
- Page
- Base
- Vertical spacing
- Link
- Literal inline
- Heading
- Title page
- Block
- Caption
- Code
- Blockquote
- Sidebar
- Example
- Admonition
- Image
- Lead
- Abstract
- Thematic break
- Description list
- Outline list
- Table
- Table of contents
- Running header & footer
Applying your theme
Theme-related document attributes

Language overview

The theme language in Asciidoctor PDF is based on the 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).

📎

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.

Underscores (_) can be used in place of hyphens (-) for all property names in the theme language.
Instead of separate properties for font weight and font style, the theme language combines these settings in the font_style property (allowed 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

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_spacing: $base_line_height_length
heading:
  font_color: #262626
  font_size: 17
  font_style: bold
  line_height: 1.2
  margin_bottom: $vertical_spacing
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, which is loaded prior to loading your custom theme. 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:

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:

base:
  font_color: #333333
  font_family: Times-Roman
  font_size: 12

Or even:

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_spacing)

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,

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.

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.

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 brand colors:

brand:
  primary: #E0162B # # (1)
  secondary: '#FFFFFF' # # (2)
  alert: '0052A5' # # (3)

To align with CSS, you may add a # in front of the hex color value. A YAML preprocessor is used to ensure the value is not treated as a comment as it would normally be the case in YAML.
You may put quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool.
The leading # on a hex value is entirely optional. However, we recommend that you always use either a leading # or surrounding quotes (or both) to prevent YAML from mangling the value.

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

base:
  font_color: $brand_primary

Math expressions & functions

The theme language supports basic math operations to support calculated values. Like programming languages, multiple and divide take precedence over add and subtract.

The following table lists the supported operations and the corresponding operator for each.

Operation	Operator
multiply	*
divide	/
add	+
subtract	-

❗	The operator must always be surrounded by a space on either side (e.g., 2 + 2 and not 2+2).

Here’s an example of a math expression with fixed values.

conum:
  line_height: 4 / 3

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

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.

❗	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.

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:

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:

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 #, optional surrounding quotes or both.
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%.
Transparent: The special value transparent indicates that a color should not be used.

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 (#), optional surrounding quotes or both.

To align with CSS, you may add a # in front of the hex color value. A YAML preprocessor is used to ensure the value is not treated as a comment as it would normally be the case in YAML.

You also may put quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool. In this case, the leading # on a hex value is entirely optional.

Regardless, we recommend that you always use either a leading # or surrounding quotes (or both) to prevent YAML from mangling the value.

The following are all equivalent values for the color red:

#f00	'f00'	#ff0000	'ff0000'
#F00	'F00'	#FF0000	'FF0000'

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

base:
  font_color: #ff0000

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.

📎	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:

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:

base:
  font_color: [0, 0.99, 1, 0]

Transparent

It’s possible to specify no color by assigning the special value transparent, as shown here:

base:
  background_color: transparent

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)

🔥	The GIF format (.gif) is not supported.

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

title_page:
  background_image: title-cover.png

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

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:

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

Fonts

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

❗

Asciidoctor has no challenge working with Unicode. In fact, it prefers Unicode and considers the whole range. However, once you convert to PDF, you have to meet the font requirements of PDF in order to preserve Unicode characters. There’s nothing Asciidoctor can do to convince PDF to work without the right fonts in play.

Built-in (AFM) fonts

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

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:

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 characters in the WINANSI (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.

WINANSI encoding behavior

If you’re using Prawn 1.3.0 with one of the built-in fonts, any characters in your AsciiDoc document that cannot be encoded to WINANSI will be replaced with an underscore glyph (_). If you’re using Prawn 2.0.0 or above with one of the built-in fonts, if your AsciiDoc document contains a character that cannot be encoded to WINANSI, a warning will be issued and conversion will halt.

For more information about how Prawn handles character encodings for built-in fonts, see this note in the Prawn CHANGELOG.

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:

Noto Serif: A serif font that can be styled as normal, italic, bold or bold_italic.
M+ 1mn: A monospaced font that maps different thicknesses to the styles normal, italic, bold and bold_italic. Also provides the circuled numbers used in callouts.
M+ 1p Fallback: 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.

🔥	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 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).

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:

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

⚠️	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:

font:
  catalog:
    Roboto:
      normal: roboto-normal.ttf
      italic: roboto-italic.ttf
      bold: roboto-bold.ttf
      bold_italic: roboto-bold_italic.ttf
    Roboto Light:
      normal: roboto-light-normal.ttf
      italic: roboto-light-italic.ttf
      bold: roboto-light-bold.ttf
      bold_italic: roboto-light-bold_italic.ttf

💡	Text in SVGs will use the font catalog from your theme. We recommend that you match the font key to the name of the font seen by the operating system. This will allow you to use the same font names (aka families) in both your graphics program and Asciidoctor PDF.

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 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).

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.

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]

💡	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.

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

Keys

This section lists all the keys that are available when creating a custom theme. The converter uses the values of these keys to control how most elements are arranged and styled in the PDF.

📎	When creating a theme, all keys are optional. You only have to assign values to keys you want to customize. Any required keys are assigned by the base theme.

The keys in this section are organized by category. Each category represents a common prefix under which the keys are typically nested. The default values are those assigned by the base theme (not the default theme).

💡	Keys can be partioned and nested wherever an underscore (`_`) appears in the name. This nested structure is flatted when the theme is loaded.

Page

The keys in this category control the size, margins and background of each page (i.e., canvas).

📎	The background of the title page can be styled independently. See Title page for details.

Key	Value Type	Example
Key Prefix: page
background_color^[1]	Color (default: #ffffff)	page: background_color: #fefefe
background_image^[1]	Inline image macro^[2] (default: none)	page: background_image: +image:page-bg.png[]+
layout	portrait \| landscape (default: portrait)	page: layout: landscape
margin	Measurement \| Measurement[top,right,bottom,left] (default: 36)	page: margin: [0.5in, 0.67in, 1in, 0.67in]
size	Named size \| Measurement[width,height] (default: A4)	page: size: Letter

Page backgrounds do not currently work when using AsciidoctorJ PDF. This limitation is due to a bug in Prawn 1.3.1. The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000). For more details, see this thread.
Target may be an absolute path or a path relative to the value of the pdf-stylesdir attribute.

Base

The keys in this category provide generic theme settings and are often referenced throughout the theme file as variables. It’s common to define additional keys in this category (e.g., base_border_radius) that serve as custom variables to help keep your theme DRY.

Key	Value Type	Example
Key Prefix: base
align	left \| center \| right \| justify (default: left)	base: align: justify
font_color	Color (default: #000000)	base: font_color: #333333
font_family	Font family name (default: Helvetica)	base: font_family: Noto Serif
font_size	Number (default: 12)	base: font_size: 10.5
font_size_min	Number (default: 9)	base: font_size_min: 6
font_style	normal \| italic \| bold \| bold_italic (default: normal)	base: font_style: normal
line_height_length^[1]	Number (default: 13.8)	base: line_height_length: 12
line_height^[1]	Number (default: 1.15)	base: line_height: > $base_line_height_length / $base_font_size
border_width	Number (default: 0.5)	base: border_width: 0.5
border_color	Color (default: #eeeeee)	base: border_color: #eeeeee

You should set one of line_height or line_height_length, then derive the value of the other using a calculation as these are correlated values. For instance, if you set line_height_length, then use $base_line_height_length / $base_font_size as the value of line_height.

Vertical spacing

The keys in this category control the general spacing between elements where a more specific setting is not designated.

Key	Value Type	Example
vertical_spacing	Number (default: 12)	vertical_spacing: 10

Link

The keys in this category are used to style hyperlink text.

Key	Value Type	Example
Key Prefix: link
font_color	Color (default: #0000ee)	link: font_color: #428bca

Literal inline

The keys in this category are used for inline monospaced text in prose and table cells.

Key	Value Type	Example
Key Prefix: literal
font_color	Color	literal: font_color: #b12146
font_family	Font family name (default: Courier)	literal: font_family: M+ 1mn
font_size	Number	literal: font_size: 12
font_style	normal \| italic \| bold \| bold_italic	literal: font_style: bold

Heading

The keys in this category control the style of most headings, including part titles, chapter titles, sections titles, the table of contents title and discrete headings.

Key	Value Type	Example
Key Prefix: heading
align	left \| center \| right \| justify (default: left)	heading: align: center
font_color	Color (default: $base_font_color)	heading: font_color: #222222
font_family	Font family name (default: $base_font_family)	heading: font_family: Noto Serif
font_size	Number (default: $base_font_size)	heading: font_size: 18
font_style	normal \| italic \| bold \| bold_italic (default: bold)	heading: font_style: bold
line_height	Number (default: 1.15)	heading: line_height: 1.2
margin_top	Measurement (default: 4)	heading: margin_top: $vertical_spacing * 0.2
margin_bottom	Measurement (default: 12)	heading: margin_bottom: 9.6
text_transform	none \| uppercase \| lowercase (default: none)	heading: text_transform: uppercase
Key Prefix: heading_h<n>^[1]
align	left \| center \| right \| justify (default: $heading_align)	heading: h2_align: center
font_color	Color (default: $heading_font_color)	heading: h2_font_color: [0, 99%, 100%, 0]
font_family	Font family name (default: $heading_font_family)	heading: h4_font_family: Roboto
font_size	Number (default: h1=24; h2=18; h3=16; h4=14; h5=12; h6=10)	heading: h6_font_size: $base_font_size * 1.7
font_style	normal \| italic \| bold \| bold_italic (default: $heading_font_style)	heading: h3_font_style: bold_italic
text_transform	none \| uppercase \| lowercase (default: $heading_text_transform)	heading: text_transform: lowercase

<n> is a number ranging from 1 to 6, representing each of the six heading levels.

Title page

The keys in this category control the style of the title page as well as the arrangement and style of the elements on it.

💡	The title page can be disabled from the document by setting the `notitle` attribute in the document header.

Key	Value Type	Example
Key Prefix: title_page
align	left \| center \| right \| justify (default: center)	title_page: align: right
background_color^[1]	Color	title_page: background_color: #eaeaea
background_image^[1]	Inline image macro^[2]	title_page: +background_image: image:title.png[]+
font_color	Color	title_page: font_color: #333333
font_family	Font family name	title_page: font_family: Noto Serif
font_size	Number	title_page: font_size: $base_font_size_large
font_style	normal \| italic \| bold \| bold_italic	title_page: font_style: bold
line_height	Number (default: 1.15)	title_page: line_height: 1
Key Prefix: title_page_logo
align	left \| center \| right	title_page: logo: align: right
image	Inline image macro^[2]	title_page: logo: +image: image:logo.png[pdfwidth=25%]+
top	Percentage (default: 10%)	title_page: logo: top: 25%
Key Prefix: title_page_title
font_color	Color	title_page: title: font_color: #999999
font_family	Font family name	title_page: title: font_family: Noto Serif
font_size	Number (default: 18)	title_page: title: font_size: $heading_h1_font_size
font_style	normal \| italic \| bold \| bold_italic	title_page: title: font_style: bold
line_height	Number	title_page: title: line_height: 0.9
top	Percentage (default: 40%)	title_page: title: top: 55%
Key Prefix: title_page_subtitle
font_color	Color	title_page: subtitle: font_color: #181818
font_family	Font family name	title_page: subtitle: font_family: Noto Serif
font_size	Number (default: 14)	title_page: subtitle: font_size: $heading_h3_font_size
font_style	normal \| italic \| bold \| bold_italic	title_page: subtitle: font_style: bold_italic
line_height	Number	title_page: subtitle: line_height: 1
Key Prefix: title_page_authors
font_color	Color	title_page: authors: font_color: #181818
font_family	Font family name	title_page: authors: font_family: Noto Serif
font_size	Number	title_page: authors: font_size: $base_font_size_large
font_style	normal \| italic \| bold \| bold_italic	title_page: authors: font_style: bold_italic
margin_top	Measurement (default: 12)	title_page: authors: margin_top: 13.125
Key Prefix: title_page_revision
font_color	Color	title_page: revision: font_color: #181818
font_family	Font family name	title_page: revision: font_family: Noto Serif
font_size	Number	title_page: revision: font_size: $base_font_size_small
font_style	normal \| italic \| bold \| bold_italic	title_page: revision: font_style: bold
margin_top	Measurement	title_page: revision: margin_top: 13.125

Page backgrounds do not currently work when using AsciidoctorJ PDF. This limitation is due to a bug in Prawn 1.3.1. The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000). For more details, see this thread.
Target may be an absolute path or a path relative to the value of the pdf-stylesdir attribute.

Block

The keys in this category control the spacing around block elements when a more specific setting is not designated.

Key	Value Type	Example
Key Prefix: block
margin_top	Measurement (default: 0)	block: margin_top: 6
margin_bottom	Measurement (default: 12)	block: margin_bottom: 6

Block styles are applied to the following block types:

admonition
example
quote

verse
sidebar
image

listing
literal
table

Caption

The keys in this category control the arrangement and style of block captions.

Key	Value Type	Example
Key Prefix: caption
align	left \| center \| right \| justify (default: left)	caption: align: left
font_color	Color	caption: font_color: #333333
font_family	Font family name	caption: font_family: M+ 1mn
font_size	Number	caption: font_size: 11
font_style	normal \| italic \| bold \| bold_italic (default: italic)	caption: font_style: italic
margin_inside	Measurement (default: 4)	caption: margin_inside: 3
margin_outside	Measurement (default: 0)	caption: margin_outside: 0

Code

The keys in this category are used to control the style of literal, listing and source blocks.

Key	Value Type	Example
Key Prefix: code
background_color	Color	code: background_color: #f5f5f5
border_color	Color (default: #eeeeee)	code: border_color: #cccccc
border_radius	Number (default: 0)	code: border_radius: 4
border_width	Number (default: 0.5)	code: border_width: 0.75
font_color	Color	code: font_color: #333333
font_family	Font family name (default: Courier)	code: font_family: M+ 1mn
font_size	Number (default: 10.5)	code: font_size: 11
font_style	normal \| italic \| bold \| bold_italic	code: font_style: italic
line_height	Number (default: 1.2)	code: line_height: 1.25
padding	Measurement \| Measurement[top,right,bottom,left] (default: 9)	code: padding: 11

Blockquote

The keys in this category control the arrangement and style of quote blocks.

Key	Value Type	Example
Key Prefix: blockquote
border_width	Number (default: 4)	blockquote: border_width: 5
border_color	Color (default: #eeeeee)	blockquote: border_color: #eeeeee
font_color	Color	blockquote: font_color: #333333
font_family	Font family name	blockquote: font_family: Noto Serif
font_size	Number	blockquote: font_size: 13
font_style	normal \| italic \| bold \| bold_italic	blockquote: font_style: bold
padding	Measurement \| Measurement[top,right,bottom,left] (default: [6, 12, -6, 14])	blockquote: padding: [5, 10, -5, 12]
Key Prefix: blockquote_cite
font_size	Number	blockquote: cite: font_size: 9
font_color	Color	blockquote: cite: font_color: #999999
font_family	Font family name	blockquote: cite: font_family: Noto Serif
font_style	normal \| italic \| bold \| bold_italic	blockquote: cite: font_style: bold

Sidebar

The keys in this category control the arrangement and style of sidebar blocks.

Key	Value Type	Example
Key Prefix: sidebar
background_color	Color (default: #eeeeee)	sidebar: background_color: #eeeeee
border_color	Color	sidebar: border_color: #ffffff
border_radius	Number	sidebar: border_radius: 4
border_width	Number	sidebar: border_width: 0.5
padding	Measurement \| Measurement[top,right,bottom,left] (default: [12, 12, 0, 12])	sidebar: padding: [12, 15, 0, 15]
Key Prefix: sidebar_title
align	left \| center \| right \| justify (default: center)	sidebar: title: align: center
font_color	Color	sidebar: title: font_color: #333333
font_family	Font family name	sidebar: title: font_family: Noto Serif
font_size	Number	sidebar: title: font_size: 13
font_style	normal \| italic \| bold \| bold_italic (default: bold)	sidebar: title: font_style: bold

Example

The keys in this category control the arrangement and style of example blocks.

Key	Value Type	Example
Key Prefix: example
background_color	Color	example: background_color: #fffef7
border_color	Color (default: #eeeeee)	example: border_color: #eeeeee
border_radius	Number (default: 0)	example: border_radius: 4
border_width	Number (default: 0.5)	example: border_width: 0.75

Admonition

The keys in this category control the arrangement and style of admonition blocks and the icon used for each admonition type.

Key	Value Type	Example
Key Prefix: admonition
border_color	Color (default: #eeeeee)	admonition: border_color: #eeeeee
border_width	Number (default: 0.5)	admonition: border_width: 0.5
padding	Measurement \| Measurement[top,right,bottom,left] (default: [0, 12, 0, 12])	admonition: padding: [0, 12, 0, 12]
Key Prefix: admonition_icon
<name>_name^[1]	String^[2]	admonition: icon: tip: name: fa-fire
<name>_stroke_color^[1]	Color	admonition: icon: tip: stroke_color: ff0000
<name>_size^[1]	Number (default: 24)	admonition: icon: tip:size: 24

<name> can be note, tip, warning, important or caution.
See the .yml files in the prawn-icon repository for a list of valid names. The prefix (e.g., fa-) determines which font set to use.

Image

The keys in this category control the arrangement of block images.

Key	Value Type	Example
Key Prefix: image
align	left \| center \| right (default: left)	image: align: left

Lead

The keys in this category control the styling of lead paragraphs.

Key	Value Type	Example
Key Prefix: lead
font_size	Number (default: 13.5)	lead: font_size: 13
line_height	Number (default: 1.4)	lead: line_height: 1.4

Abstract

The keys in this category control the arrangement and style of the abstract.

Key	Value Type	Example
Key Prefix: abstract
font_color	Color	abstract: font_color: #5c6266
font_size	Number (default: 13.5)	abstract: font_size: 13
font_style	normal \| italic \| bold \| bold_italic	abstract: font_style: italic
line_height	Number (default: 1.4)	abstract: line_height: 1.4
padding	Measurement \| Measurement[top,right,bottom,left] (default: 0)	abstract: padding: [0, 12, 0, 12]

Thematic break

The keys in this category control the style of thematic breaks (aka horizontal rules).

Key	Value Type	Example
Key Prefix: thematic_break
border_color	Color (default: #eeeeee)	thematic_break: border_color: #eeeeee
border_style	solid \| double \| dashed \| dotted (default: solid)	thematic_break: border_style: dashed
border_width	Measurement (default: 0.5)	thematic_break: border_width: 0.5
margin_top	Measurement	thematic_break: margin_top: 6
margin_bottom	Measurement	thematic_break: margin_bottom: 18

Description list

The keys in this category control the arrangement and style of definition list items (terms and descriptions).

Key	Value Type	Example
Key Prefix: description_list
term_font_style	normal \| italic \| bold \| bold_italic	description_list: term_font_style: italic
term_spacing	Measurement (default: 4)	description_list: term_spacing: 5
description_indent	Number (default: 30)	description_list: description_indent: 15

Outline list

The keys in this category control the arrangement and style of outline list items.

Key	Value Type	Example
Key Prefix: outline_list
indent	Measurement (default: 30)	outline_list: indent: 40
item_spacing	Measurement (default: 6)	outline_list: item_spacing: 4

Table

The keys in this category control the arrangement and style of tables and table cells.

Key	Value Type	Example
Key Prefix: table
background_color	Color	table: background_color: #ffffff
border_color	Color (default: #000000)	table: border_color: #dddddd
border_width	Number (default: 0.5)	table: border_width: 0.5
font_color	Color (default: $base_font_color)	table: font_color: #333333
font_family	Font family name	table: font_family: Helvetica
font_size	Number	table: font_size: 9.5
grid_color	Color (default: $table_border_color)	table: grid_color: #eeeeee
grid_width	Number (default: $table_border_width)	table: grid_width: 0.5
Key Prefix: table_head
background_color	Color (default: $table_background_color)	table: head: background_color: #f0f0f0
font_color	Color (default: $table_font_color)	table: head: font_color: #333333
font_family	Font family name (default: $table_font_family)	table: head: font_family: Noto Serif
font_size	Number (default: $table_font_size)	table: head: font_size: 10
font_style	normal \| italic \| bold \| bold_italic (default: bold)	table: head: font_style: normal
text_transform	none \| uppercase \| lowercase (default: none)	table: head: text_transform: uppercase
Key Prefix: table_foot
background_color	Color (default: $table_background_color)	table: foot: background_color: #f0f0f0
font_color	Color (default: $table_font_color)	table: foot: font_color: #333333
font_family	Font family name (default: $table_font_family)	table: foot: font_family: Noto Serif
font_size	Number (default: $table_font_size)	table: foot: font_size: 10
font_style	normal \| italic \| bold \| bold_italic (default: normal)	table: foot: font_style: italic
Key Prefix: table_<parity>_row^[1]
background_color	Color	table: even_row: background_color: #f9f9f9
Key Prefix: table_cell
padding	Measurement \| Measurement[top,right,bottom,left] (default: 2)	table: cell: padding: [3, 3, 6, 3]
Key Prefix: table_header_cell
align	left \| center \| right	table: header_cell: align: center
background_color	Color	table: header_cell: background_color: #f0f0f0
font_color	Color	table: header_cell: font_color: #1a1a1a
font_family	Font family name	table: header_cell: font_family: Noto Sans
font_size	Number	table: header_cell: font_size: 12
font_style	normal \| italic \| bold \| bold_italic	table: header_cell: font_style: italic

<parity> can be odd (odd rows) or even (even rows).

Key	Value Type	Example
Key Prefix: toc
font_color	Color	toc: font_color: #333333
font_family	Font family name	toc: font_family: Noto Serif
font_size	Number	toc: font_size: 9
font_style	normal \| italic \| bold \| bold_italic	toc: font_style: bold
line_height	Number (default: 1.4)	toc: line_height: 1.5
indent	Measurement (default: 15)	toc: indent: 20
margin_top	Measurement	toc: margin_top: 0
Key Prefix: toc_h<n>^[1]
font_color	Color	toc: h3_font_color: #999999
Key Prefix: toc_title^[2]
align	left \| center \| right \| justify (default: left)	toc: title: align: center
Key Prefix: toc_dot_leader
content	Quoted string	toc: dot_leader: content: ". "
color	Color	toc: dot_leader: color: #999999

<n> is a number ranging from 1 to 6, representing each of the six heading levels.
The toc_title keys inherit from level-2 heading styles, except where noted.

Running header & footer

The keys in this category control the arrangement and style of running header and footer content.

💡	You can disable the running header and footer by setting the `noheader` and `nofooter` attributes in your document, respectively.

Key	Value Type	Example
Key Prefix: header
background_color	Color	header: background_color: #eeeeee
border_color	Color	header: border_color: #dddddd
border_style	solid \| double \| dashed \| dotted (default: solid)	header: border_style: dashed
border_width	Measurement	header: border_width: 0.25
font_color	Color	header: font_color: #333333
font_family	Font family name	header: font_family: Noto Serif
font_size	Number	header: font_size: 9
font_style	normal \| italic \| bold \| bold_italic	header: font_style: italic
height	Measurement	header: height: 0.75in
line_height	Number (default: $base_line_height)	header: line_height: 1.2
padding	Measurement \| Measurement[top,right,bottom,left]	header: padding: [0, 3, 0, 3]
image_vertical_align	top \| middle \| bottom \| Measurement	header: image_vertical_align: 4
vertical_align	top \| middle \| bottom	header: vertical_align: center
<face>_content_<position>^[1]	Quoted string	header: recto_content: left: '\{page-number}'
Key Prefix: footer
background_color	Color	footer: background_color: #eeeeee
border_color	Color	footer: border_color: #dddddd
border_style	solid \| double \| dashed \| dotted (default: solid)	footer: border_style: dashed
border_width	Measurement	footer: border_width: 0.25
font_color	Color	footer: font_color: #333333
font_family	Font family name	footer: font_family: Noto Serif
font_size	Number	footer: font_size: 9
font_style	normal \| italic \| bold \| bold_italic	footer: font_style: italic
height	Measurement	footer: height: 0.75in
line_height	Number (default: $base_line_height)	footer: line_height: 1.2
padding	Measurement \| Measurement[top,right,bottom,left]	footer: padding: [0, 3, 0, 3]
image_vertical_align	top \| middle \| bottom \| Measurement	footer: image_vertical_align: 4
vertical_align	top \| middle \| bottom	footer: vertical_align: top
<face>_content_<position>^[1]	Quoted string	footer: verso_content: center: '\{page-number}'

<face> can be recto (odd pages) or verso (even pages). <position> can be left, center or right.

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

💡	The running header and footer can be disabled from the document by setting the `noheader` and the `nofooter` attributes, respectively, in the document header.

📎	If content is not specified for the running footer, the page number (i.e., `{page-number}`) will be shown on the left side on verso pages and the right side on recto pages.

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

Attribute references

You can use any attribute defined in your AsciiDoc document in the content of the running header and footer. In addition, the following attributes are also 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

You can also built-in AsciiDoc text replacements like (C), numeric character references like © and inline formatting (e.g., bold, italic, monospace).

Here’s an example that shows how attributes and replacements can be used in the running footer:

header:
  height: 0.75in
  line_height: 1
  recto_content:
    center: '(C) ACME -- v{revnumber}, {docdate}'
  verso_content:
    center: $header_recto_content_center
footer:
  height: 0.75in
  line_height: 1
  recto_content:
    right: '{section-or-chapter-title} | *{page-number}*'
  verso_content:
    left: '*{page-number}* | {chapter-title}'

You can split the content value across multiple lines using YAML’s multiline string syntax. In this case, the single quotes around the string are not necessary. To force a hard line break in the output, add + to the end of the line in normal AsciiDoc fashion.

footer:
  height: 0.75in
  line_height: 1.2
  recto_content:
    right: |
      Section Title - Page Number +
      {section-or-chapter-title} - {page-number}
  verso_content:
    left: |
      Page Number - Chapter Title +
      {page-number} - {chapter-title}

💡	You can use most AsciiDoc inline formatting in the values of these keys. For instance, to make the text bold, surround it in asterisks (as shown above). One exception to this rule are inline images, which are described in the next section.

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).

header:
  height: 0.75in
  image_vertical_align: 2 # # (1)
  recto_content:
    center: image:footer-logo.png[width=80]
  verso_content:
    center: $header_recto_content_center

You can use the footer_vertical_align attribute to slighly nudge the image up or down.

🔥	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.

📎	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

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.

Maven Example
Gradle Example

Theme-related document attributes

There are various settings in the theme you control using document attributes. These settings override equivalent keys defined in the theme file, where applicable.

Attribute	Value Type	Example
autofit-option	flag (default: not set)	`:autofit-option:`
chapter-label	string (default: Chapter)	`:chapter-label: Chapter`
<face>-cover-image	inline image macro (target is relative to `imagesdir`; can be image or PDF file)	`:front-cover-image: image:front-cover.pdf[]`
pagenums^[2]	flag (default: set)	`:pagenums:`
pdf-page-size	named size, measurement dimensions (width x height)	`:pdf-page-size: 6in x 9in`
title-logo-image	inline image macro (path is relative to `imagesdir`; can be image or PDF file)	`:title-logo-image: image:logo.png[top=25%, align=center, pdfwidth=0.5in]`

<face> can be front or back.
Controls whether the page-number attribute is accessible to the running header and footer content specified in the theme file. Use the noheader and nofooter attributes to disable the running header and footer, respectively, from the document.

Files

theming-guide.adoc

Latest commit

History

theming-guide.adoc

File metadata and controls

Asciidoctor PDF Theming Guide

Language overview

Values

Inheritance

Variables

Custom variables

Math expressions & functions

Measurement units

Colors

Hex

RGB

CMYK

Transparent

Images

Fonts

Built-in (AFM) fonts

Bundled fonts

Custom fonts

Fallback fonts

Keys

Page

Base

Vertical spacing

Link

Literal inline

Heading

Title page

Block

Caption

Code

Blockquote

Sidebar

Example

Admonition

Image

Lead

Abstract

Thematic break

Description list

Outline list

Table

Table of contents

Running header & footer

Attribute references

Images

Applying your theme

Theme-related document attributes