Asciidoctor PDF Theming Guide

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

A theme 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.

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

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

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

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

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 (_) or hyphen (-). 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 or 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:

Or, to avoid having to type the prefix base- multiple times, the keys may be written as a hierarchy:

Or even:

Each level of nesting must be indented by two spaces from the indentation of the parent level. Also note the presence of the colon (:) after each key name.

Like CSS, inheritance is a principle 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

• text-transform

• line-height (currently some exceptions)

• margin-bottom (if not specified, defaults to $vertical-spacing)

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 sign ($) (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,

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.

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.

We’ll cover more about math expressions later.

Custom Variables

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

base:
  font-color: $brand-primary-color

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

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

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

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

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.

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.

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. If you specify a number without any units, the units defaults to pt.

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:

1. A percentage with the % unit is calculated relative to the width or height of the content area. Viewport-relative percentages (vw or vh units) are calculated as a percentage of the page width or height, respectively. Currently, percentage units can only be used for placing elements on the title page or for setting the width of a block image.

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

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

1. top

2. right

3. bottom

4. left

The align subkey is used to align text and images within the parent container.

Text Alignments

Text Decorations

Image Alignments

In most cases, wherever you can specify a custom font family, you can also specify a font style. These two settings are combined to locate the font to use.

The following font styles are recognized:

• normal (no style)

• italic

• bold

• bold_italic

Many places where font properties can be specified, a case transformation can be applied to the text. The following transforms are recognized:

• uppercase

• lowercase

• capitalize (each word, like CSS)

• none (clears an inherited value)

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

base:
  font-color: #ff0000

RGB

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

base:
  font-color: [255, 0, 0]

CMYK

base:
  font-color: [0, 0.99, 1, 0]

Transparent

table:
  background-color: transparent

An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax. Images in the theme file are currently resolved relative to the value of the pdf-themesdir attribute. (If pdf-theme is a path that ends in .yml, and pdf-themesdir is not set, then the images are resolved relative to the directory of the path specified by pdf-theme). If you want to use an image in your theme that’s relative to the document you’re converting, you can prefix the target with the attribute reference.

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

• PNG (.png)

• JPEG (.jpg)

• SVG (.svg)

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

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

In either case, the image is resolved relative to the value of the pdf-themesdir attribute, as previously described. If you want to instead reference an image relative to the document you’re converting, then prefix the target with the attribute reference.

Like in the AsciiDoc syntax, wrapping the value in the image macro allows you to specify other settings, such as pdfwidth, fit, and/or align. For example:

Some of the keys accept a quoted string as text content. The final segment of these keys is always named content.

A content key accepts a string value. It’s usually best to quote the string or use the YAML multi-line string syntax.

Text content may be formatted using a subset of inline HTML. You can use the well-known elements such as <strong>, <em>, <code>, <a>, <sub>, <sup>, <del>, and <span>. The <span> element supports the style attribute, which you can use to specify the color, font-weight, and font-style CSS properties. You can also use the rgb attribute on the <color> element to change the color or the name and size attributes on the <font> element to change the font properties. If you need to add an underline or strikethrough decoration to the text, you can assign the underline or line-through to the class attribute on any aforementioned element.

Here’s an example of using formatting in the content of the menu caret:

Additionally, normal substitutions are applied to the value of content keys for running content, so you can use most AsciiDoc inline formatting (e.g., *strong* or {attribute-name}) in the values of those keys.

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

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:

However, when you use a built-in font, the characters you can 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.

Asciidoctor PDF bundles several fonts that are used by the default theme. You can also use these fonts in your custom theme by simply declaring them. These fonts provide more characters than the built-in PDF fonts, but still only a subset of UTF-8 (to reduce the size of the gem).

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. Used as the fallback font in the default-with-fallback-font theme.

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

Selecting Your Font

Asciidoctor PDF cannot italicize a font dynamically like a browser can, so the italic styles are required to italicize text.

Declaring Your Font

font:
  catalog:
    merge: false # set value to true to merge catalog with theme you're extending
    Roboto:
      normal: roboto-normal.ttf
      italic: roboto-italic.ttf
      bold: roboto-bold.ttf
      bold_italic: roboto-bold_italic.ttf

font:
  catalog:
    merge: false # set value to true to merge catalog with theme you're extending
    VLGothic: vlgothic.ttf

font:
  catalog:
    merge: false # set value to true to merge catalog with theme you're extending
    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

heading:
  font-family: Roboto
  font-style: bold

Configuring the Font Search Path

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

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

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

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

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

Subsetting Your Font

If a TrueType font is missing a character needed to render the document, such as a special symbol or emoji, you can have Asciidoctor PDF look for the character in a fallback font.

You only need to specify a single fallback font, typically one that provides a full set of symbols. If the character isn’t found in the fallback font, it will mostly likely be replaced by a box (i.e., the notdef glyph), which is guaranteed if you’re using the bundled fallback font.

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

Notice that we only declare the fallback font file once using a literal value. This ensures the font is defined for all four variants so it will be used regardless of which font style is active when it’s called on. This assignment is equivalent to the following:

The benefit of this syntax is that it allows you to use a separate font file for just one of the variants (e.g., bold).

Next, add the key name to the fallbacks key under the font-catalog key. The fallbacks key accepts an array of values, meaning you can specify more than one fallback font. However, we recommend using a single fallback font, if possible, as shown here:

Of course, make sure you’ve configured your theme to use your custom font:

That’s it! Now you’re covered. If your custom TTF font is missing a glyph, Asciidoctor PDF will look in your fallback font. You don’t need to reference the fallback font anywhere else in your theme file.

Here’s another example that shows how to use an alternative emoji font (Symbola):

Now Asciidoctor PDF will look for the emoji in the Symbola font instead of the Noto Emoji font.

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

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

Currently, the theme starts out empty. Then, the files referenced by the extends key are loaded in order. Finally, the keys in the current file are loaded. Each time a theme is loaded, the keys are overlaid onto the keys from the previous theme.

If you define a font catalog in a theme that extends from default, and you want to continue to use the bundled fonts in your theme, you either have to redeclare the bundled fonts:

or you need to set merge: true above your font definitions:

If you’re referring to a bundled font, you’ll need to prefix the path with GEM_FONTS_DIR (or add it to the value of the pdf-fontsdir attribute) so the converter can find and register it. You can find the bundle font definitions in default theme.

The keys in the role category define custom roles for formatting. The name of the role is the first subkey level. The role name may contain a hyphen, but a role name cannot contain an underscore. The keys under the role are the theming properties.

Here’s an example of a role for making text red:

This role can be used as follows:

You can also use a role to unset a font color (to make it inherit):

This role can be used as follows:

The converter provides several predefined roles, which can can all be redefined. The big and small roles map the font size to the $base-font-size-large and $base-font-size-small values, respectively. The underline and line-through roles add the underline and strikethrough decorations, respectively. The subtitle role is used to configure the font properties of the subtitle of a section title. The color roles (e.g., blue), which you may be familiar with from the HTML converter, are not mapped by default. You’ll need to define these color roles in your theme if you’d like to make use of them when converting to PDF.

The keys in this category control the front and back cover images. Currently, the only supported feature is setting the image per side.

1. <face> can be front or back.

2. The value may be an image file or a PDF file. A relative path will be resolved relative to the value of the pdf-themesdir attribute. An image files is handled just like a background image. If a PDF file is specified, the first page is used unless another page is specified by the page attribute. The page from the PDF file will be imported as is.

The keys in this category control the size, margins and background of each page (i.e., canvas). We recommended that you define this category before all other categories.

1. To disable the background color for the page, set the value to white (i.e., FFFFFF). The color keyword transparent is not recognized in this context.

2. By default, page background and foreground images are automatically scaled to fit the bounds of the page (i.e., fit=contain) and centered (i.e., position=center). The size of the image can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width) when fit=none. The position of the image can be controlled using the position attribute. If the recto (right-hand, odd-numbered pages) or verso (left-hand, even-numbered pages) background image is specified, it will be used only for that side (not available for the foreground image). If you define the keys using the flatten structure (e.g., page-background-image-recto), you can also set the default page background image (page-background-image), which will then be used as a fallback if a background image isn’t specified for a given side. To disable the image, use the value none.

3. Target may be an absolute path or a path relative to the value of the pdf-themesdir attribute.

4. The margins for recto (right-hand, odd-numbered) and verso (left-hand, even-numbered) pages are calculated automatically from the margin-inner and margin-outer values. These margins and used when the value prepress is assigned to the media document attribute. If no cover is specified, the recto margin is not applied to the title page. To apply the recto margin to the title page, but not include a cover, assign the value ~ to the front-cover-image attribute.

5. The title and toc values are only recognized if the title page is enabled (i.e., doctype is book or title-page attribute is set) The toc value only applies if the toc is in the default location (before the first page of the body). If the toc macro is used to position the toc, the start-at behavior is the same as if the toc is not enabled. If value is an integer, page numbering will start at the specified page of the body (i.e., 1 is first page, 2 is second page, etc.)

The keys in this category provide generic theme settings and are often referenced throughout the theme file as variables. We recommended that you define this category after the page category and before all other categories.

1. The text-transform key cannot be set globally. Therefore, this key should not be used. The value of none is implicit and is documented here for completeness.

2. line-height-length is a utility property that’s internal to the theme. It’s used as an intermediate property for computing the base-line-height from the base font size and the desired line height size. For instance, if you set base-line-height-length, you can use $base-line-height-length / $base-font-size to set the value of base-line-height. You don’t have to go about it this way in your own theme.

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

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

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

1. The border is only used if a border color is specified and the border width is not explicitly set to 0. The border only works properly if the literal phrase does not have nested formatting. Otherwise, the border will be inherited, producing a less than desirable result.

2. The border offset is the amount that the background and border swells around the text. It does not affect the distance between the formatted phrase and the phrases that surround it.

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.

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

2. A font size is assigned to each heading level by the base theme. If you want the font size of a specific level to be inherited, you must assign the value null (or ~ for short).

The keys in this category control the style of a section body.

1. Applies to the section body only, excluding section titles and discrete headings. A single value gets applied to both the left and right side (e.g., 0.5in). A two-value array configures the left and right side independently (e.g., [0.5in, 0]).

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

1. To disable the background color for the title page, set the value to white (i.e., FFFFFF). The color keyword transparent is not recognized in this context.

2. By default, page background images are automatically scaled to fit the bounds of the page (i.e., fit=contain) and centered (i.e., position=center). The size of the background image can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width) when fit=none. The position of the background image can be controlled using the position attribute.

3. Target may be an absolute path or a path relative to the value of the pdf-themesdir attribute.

4. % unit is relative to content height; vh unit is relative to page height.

The keys in this category control the spacing around paragraphs (paragraph blocks, paragraph content of a block, and other prose content). Typically, all the margin is placed on the bottom.

1. Controls the margin between adjacent paragraphs. Useful when using indented paragraphs.

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

Block styles are applied to the following block types:

The keys in this category control the arrangement and style of block captions. In addition to the generic caption category, each of these keys (except for text decoration) can be set on the caption key nested inside the following block categories: blockquote, code, example, footnotes, image, listing, table, and verse.

1. When nested inside the image key (i.e., image-caption-align), the value inherit is also accepted. The value inherit resolves to the alignment of the block image.

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

1. The line-gap property is used to tune the height of the background color applied to a span of block text highlighted using Rouge.

2. The code-highlight category only applies when using Rouge as the source highlighter. Otherwise, the styles are controlled by the source highlighter theme.

3. The code-linenum category only applies when using Pygments as the source highlighter. Otherwise, the styles are controlled by the source highlighter theme.

The keys in this category are used to control the style of callout numbers (i.e., conums) inside verbatim blocks and in callout lists (colists).

1. Currently, the font must contain the circle numbers starting at glyph U+2460.

2. font-family, font-kerning, font-size, font-style, and line-height are only used for markers in a colist. These properties are inherited for conums inside a verbatim block.

3. The font must provide the required glyphs. The glyphs can be specified as a comma-separated list of ranges, where the range values are Unicode numbers (e.g., \u2460). Unicode escape sequences are recognized even if the value is not enclosed in double quotes.

The keys in this category apply to a button reference (generated from the inline button macro).

1. The border is only used if a border color is specified and the border width is not explicitly set to 0.

2. The border offset is the amount that the background and border swells around the text. It does not affect the distance between the formatted phrase and the phrases that surround it.

3. The character sequence %s in the content key gets replaced with the button label.

The keys in this category apply to a key reference (generated from the inline kbd macro).

1. The border is only used if a border color is specified and the border width is not explicitly set to 0.

2. The border offset is the amount that the background and border swells around the text. It does not affect the distance between the formatted phrase and the phrases that surround it.

3. The separator is only used for multi-key sequences.

The keys in this category apply to the menu label (generated from the inline menu macro).

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

1. If border-left-width is non-zero, the border is only applied to the left side. Otherwise, if border-width is non-zero, the border is drawn around the whole block.

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

1. If border-left-width is non-zero, the border is only applied to the left side. Otherwise, if border-width is non-zero, the border is drawn around the whole block.

2. The verse block does not use a fixed-width font by default, which can affect the layout if the content relies on columns. You can change verse blocks to use a fixed-width font (not necessarily a monospaced font) using this setting.

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

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

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

1. The top and bottom padding values are ignored on admonition-label-padding.

2. <name> can be note, tip, warning, important, or caution. All icon types must be grouped under a single icons category. In other words, do not declare the icons category multiple times. The subkeys in the icon category cannot be flattened (e.g., tip-name: far-lightbulb is not valid syntax).

3. Required. See the .yml files in the prawn-icon repository for a list of valid icon names. The prefix (e.g., fas-) determines which font set to use. If the prefix is not specified, fa- is assumed.

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

1. Only applies to block images. If specified, this value takes precedence over the value of the width attribute on the image macro, but not over the value of the pdfwidth attribute.

2. The border is only used if a border color is specified, the border width is specified, the border width is greater than 0, and the noborder role is not present. The border is drawn above the image on the inside of the box reserved for the image.

3. The value auto means the border should expand to fit the width of the container (i.e., full width) instead of the image.

4. Use the placeholders %{alt}, %{target}, %{link}, and %{/link} to insert the alt text, image target, and link open/close tags into the content template.

5. In order for the image to be sized correctly when max-width is fit-content, a width should always be specified on the image.

The keys in this category control the SVG integration.

1. The fallback font family is only used when the font family in the SVG does not map to a known font name from the font catalog.

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

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

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

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

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

1. Controls the color of the bullet glyph that marks items in unordered lists and the number for items in ordered lists.

2. Controls the alignment of the list text only, not nested content (blocks or lists).

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

1. <type> is one of disc, square, circle, checked, unchecked

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

1. This key only controls the color that is used for stripes. The appearance of stripes is controlled using the stripes table attribute, the table-stripes document attribute (since Asciidoctor 2), or the stripes document attribute (prior to Asciidoctor 2). Permitted attribute values are even, odd, all, and none. Prior to Asciidoctor 2, even rows are shaded by default (e.g., stripes=even). Since Asciidoctor 2, table stripes are not enabled by default (e.g., stripes=none).

The keys in this category control the style of the footnotes list at the end of the chapter (book) or document (otherwise). If the footnotes-title attribute is specified, it is styled as a block caption. The styling of the links is controlled by the global link styles.

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