AsciiDoc Attributes for PDF

Asciidoctor PDF supports additional built-in document attributes that are used by the PDF converter. These attributes can control certain aspects of PDF rendering, such as the PDF media, launch mode, outline, optimization, text hyphenation, as well as some document-specific theme settings such as the front and back cover images, the background images, the title page logo and background images, page dimensions, and more.

Relationship to theme

The theme-oriented attributes overlap with settings controlled by the PDF theme. These attributes are not meant to be a replacement for the theming system. Rather, they’re provided as a convenience to control some theme settings that are frequently changed per document or conversion and thus warrant an override.

For maximum control over the theming (aka branding) of the PDF, you’ll want to use a theme. You can either create the theme anew or extend from a built-in theme. Once you’ve created a theme, you’ll need to apply it when converting the document.

If an AsciiDoc attribute for PDF correlates to a key in the theme file, the AsciiDoc attribute always takes precedence.

Reference

If an attribute is marked as "Header Only", it only takes effect if defined by the end of the AsciiDoc document header. This designation includes attributes that are set via the API or CLI.

Attribute Value Type Header Only Example

autofit-option

flag (default: not set)

No

:autofit-option:

<face>-cover-image[1]

path[2] | image macro[3]
(format can be image or PDF)

Yes

:front-cover-image: image:front-cover.pdf[]

hyphens[5]

language code | blank to default to en_us (default: not set)

Yes

:hyphens: de

icons

font | image (default: not set)

No

:icons: font

footnotes-title

String

Yes

:footnotes-title: Endnotes

index-pagenum-sequence-style

term | page | range (default: term)

No

:index-pagenum-sequence-style: page

media

screen | print | prepress

Yes

:media: prepress

compress

flag (default: not set)

Yes

:compress:

optimize

screen | ebook | printer | prepress | default (default: default)

Yes

:optimize: prepress

outline

flag (default: set)

Yes

:outline:

outline-title

flag | String (default: set)

Yes

:outline-title: Outline

outlinelevels

Integer | Integer:Integer (default: same as toclevels)

Yes

:outlinelevels: 2

page-background-image

path[2] | image macro[3]

Yes

:page-background-image: image:bg.jpg[]

page-background-image-(recto | verso)

path[2] | image macro[3]

Yes

:page-background-image-recto: image:bg-recto.jpg[]

page-foreground-image

path[2] | image macro[3]

Yes

:page-foreground-image: image:watermark.svg[]

pagenums

flag (default: set)

Yes

:pagenums:

pdf-page-layout

portrait | landscape

Yes

:pdf-page-layout: landscape

pdf-page-margin

Measurement | Measurement[top,right,bottom,left]

Yes

:pdf-page-margin: [1in, 0.5in]

pdf-page-margin-rotated

Measurement | Measurement[top,right,bottom,left]

Yes

:pdf-page-margin-rotated: [0.5in, 0.25in]

pdf-page-mode

outline | none | thumbs | fullscreen | fullscreen outline | fullscreen none | fullscreen thumbs (default: outline)

Yes

:pdf-page-mode: fullscreen none

pdf-page-size

Named size | Measurement[width, height]

Yes

:pdf-page-size: [6in, 9in]

pdf-folio-placement

virtual | virtual-inverted | physical | physical-inverted

Yes

:pdf-folio-placement: physical

pdf-version

1.3 | 1.4 | 1.5 | 1.6 | 1.7 (default: 1.4)

Yes

:pdf-version: 1.7

pdfmark[4]

flag (default: not set)

Yes

:pdfmark:

scripts[6]

cjk (default: not set)

Yes

:scripts: cjk

text-align[7]

Text alignment

Yes

:text-align: left

title-logo-image

path[2] | image macro[3]

Yes

:title-logo-image: image:logo.png[top=25%, align=center, pdfwidth=0.5in]

title-page

flag (default: not set)

Yes

:title-page:

title-page-background-image

path[2] | image macro[3]

Yes

:title-page-background-image: image:title-bg.jpg[]

toc-max-pagenum-digits[8]

Integer (default: 3)

Yes

:toc-max-pagenum-digits: 4

  1. <face> can be front or back.

  2. A bare path is resolved relative to base_dir, which defaults to the document directory.

  3. The target of the image macro is resolved relative to imagesdir since it’s defined in the AsciiDoc document (unlike in the theme, where it is resolved relative to the value of pdf-themesdir).

  4. Enables generation of the pdfmark file, which contains metadata that can be fed to Ghostscript when optimizing the PDF file. If you’re using Ghostscript >= 8.54, this feature is not needed.

  5. Activates hyphenation for the language code specified (defaults to en_us) if the text-hyphen gem is available. If the hyphens attribute is set in the document, it overrides the base-hyphens key set in the theme. In either case, if the value is empty, then the value of the lang document attribute is used as the hyphenation language.

  6. Activates line break rules for CJK languages (specifically Chinese and Japanese). Chinese and Japanese are written without spaces (and may not use spaces when mixing with English words either). This setting allows a line break to be placed between any two CJK characters to accommodate wrapping. These languages also use different punctuation for pause, full stop, and dash, which are taken into account when breaking lines.

  7. The text-align document attribute is intended as a simple way to toggle text justification. The value of this attribute overrides the base-text-align key set by the theme. If a text-<align> role is set on a block element, that alignment always takes precedence over the theme.

  8. If the TOC overlaps the first page of content, increase this number.