What’s New in Asciidoctor PDF 2.0

The theme can now control the padding on a block using a 2-value array for ends and sides or 3-value array with implied left side value.

The border width of delimited blocks, admonitions, and block images can be customized per edge with the border-width key.

The border style of delimited blocks, admonitions, and block images can be changed with the border-style key. Border styles include dashed, dotted, double, and solid.

Wherever font properties are accepted in the theme, you can now control the line height of blocks using the line-height key.

The anchor location for blocks can be positioned relative to the content using the block-anchor-top theme key.

The text alignment of captions can now be controlled independent of the block alignment using the global caption-text-align theme key or per block category with <category>-caption-text-align. The image-caption-text-align and table-caption-text-align theme keys accept the value inherit in addition to the standard text alignment values. The value inherit resolves to the alignment of the block image or table.

The text decoration style, color, and width can be applied to captions globally with the caption-text-decoration-style, caption-text-decoration-color, and caption-text-decoration-width theme keys. See Caption Category Keys for more information.

You can now specify a background color for captions globally using the caption-background-color theme key or per block category (<category>-caption-background-color). See Caption Category Keys for more information.

A caption’s max-width value can be set to a percentage of the content by passing the percentage as an argument to fit-content function.

The theme can control the font color of first line of abstract using abstract-first-line-font-color key.

The table border width can be customized per edge with the border-width key. The border style can be specified per edge by assigning an array of styles to the border-style key. Border styles include dashed, dotted, and solid.

The width of table grid lines can be specified for rows and columns with the grid-width key. The style of the grid lines can be specified for rows and columns with the grid-style key. Grid styles include dashed, dotted, and solid. Thank you to @hextremist for adding the ability to style the horizontal and vertical lines of the table grid independently.

The maximum caption width for tables can be set to a percentage of the content by passing an argument to the fit-content function.

The table-caption-side theme key has been renamed to table-caption-end.

You can now configure whether the caption for a block image is placed above or below the image using the caption-end theme key. See Block Image Category Keys for the list of available image-caption theme keys and their value types.

The text alignment roles, such as text-center, are now supported on block images.

Roles and inherited roles are now supported on inline images.

Asciidoctor PDF 2.0 now supports image-based icons. They’re resolved from iconsdir and should have the icontype file extension.

The link attribute can now be set on the icon macro.

An admonition icon image can now be remote, if allow-uri-read is set, or a data URI. The textual label on an admonition is displayed if the icon image fails to embed.

You can now control the background color and border offset (only for background) of links from the theme.

The id attribute can now be set on the link macro.

You can now define single and double quotation marks, such as › and », using the quotes key in the theme. See Quotes Category Keys for details. Thank you to @klonfish for adding this feature to the theming language.

Character references that contain both uppercase and lowercase hexadecimal characters are now supported. Thank you to @etihwnad for adding this capability.

The text-transform theme key now accepts the smallcaps value. When smallcaps is specified, the lowercase letters are replaced with the small capital letter variants.

The new normal_italic value for the font-style key resets the font style to normal, then applies the italic variant of a font family.

Noto Sans is now bundled with Asciidoctor PDF. It is used as a fallback font in the sans-with-fallback-font theme and can be declared in a custom theme.

The left and right ceiling and floor characters (⌈, ⌉, ⌊, and ⌋)were added to the M+ fallback font. Thank you to @oddhack for adding these characters to the font subset.

The heavy checkmark glyph (✔) was added to the fallback font; the checkmark and heavy checkmark (✓ and ✔) were added to the monospaced font; the № and ÿ glyphs were added to the default and fallback fonts.

The front and back cover images can now be defined in the theme and the target can be a data URI.

The title page can now be deactivated from the theme by assigning false to the title-page category key.

You can now deactivate the PDF outline by unsetting the outline document attribute (:!outline:) as well as customize its title with outline-title and the section level depth and expansion with outlinelevels. See PDF Outline for details.

The header or footer can be deactivated on TOC pages by assigning the noheader or nofooter options on the toc macro.

The theme can control the font size of the dot leader in the TOC.

The TOC can now be placed following the preamble by assigning the preamble value to the :toc: document attribute. Also, the TOC is only displayed at the first location of a toc macro.

An extended converter can now override the get_entries_for_toc method to insert or filter TOC entries.

Footnote numbering is now reset in each chapter.

The xreftext of a chapter is now added to the label of a footnote reference that refers to a previous chapter.

The theme can configure the font color of an unresolved footnote using the unresolved role.

The theme can now configure the number of index columns using the index-columns key.

The new index-pagenum-sequence-style document attribute controls the style of sequential page numbers in the index when media=screen.

The basic running footer is now enabled when you use the base theme or extend the base theme. (Previously, the basic running footer was only enabled if you used or extended the default theme.)

Specify the page on which the running content starts being displayed by assigning an integer to the start-at theme key on the running-content category. Running content can also start after the TOC, wherever the TOC is placed, by assigning the keyword after-toc to the start-at key.

Specify the page on which the integer (1-based) page numbering begins using the start-at key on the page-numbering category. Integer page numbering can start at the front cover by assigning the keyword cover to the start-at key. Or, you can have the page numbering start after the TOC, wherever the TOC is placed, by assigning after-toc to the start-at key. Alternatively, the theme can specify an offset from the first body page where the page numbering should begin when an integer is assigned to start-at.

The margin and content margin of the running content per periphery (header or footer) and per side (recto or verso) can now be configured from the theme. The margins in running content can be specified using a 2-value array for ends and sides or 3-value array with implied left side value.

If the partnums attribute is set, the part-numeral attribute is automatically set in the running content. If the sectnums attribute is set, the chapter-numeral attribute is automatically set in the running content.

The page-layout attribute is now set in the running content. You can use this attribute to select a background per layout.

Asciidoctor PDF 2.0 has two new print-optimized themes, named default-for-print and default-for-print-with-fallback-font.

A custom theme no longer inherits from the base theme by default (i.e., when the extends key is not specified). Instead, it starts with no keys set, such as base-font-size. If you’re getting errors after upgrading, this might be the culprit. To make your theme portable across versions of Asciidoctor PDF, explicitly declare which theme you want your theme to extend (e.g., add extends: base as the first key).

Asciidoctor PDF only extends a theme in the extends hierarchy once unless the theme is modified with !important.

The theming language now supports the power operator. It has the same precedence as multiply and divide.

A Rouge theme can now be specified as a theme class or instance (API only).

The top and bottom padding on quote and verse blocks has been reduced in the base theme. The base-border-color is now set and used as the default border color. The border colors have been removed in the base theme so all border colors can be controlled using the base-border-color key when extending the theme.

The top and bottom padding on quote blocks is now uniform in the default theme.