AsciiDoc Attributes for PDF

Asciidoctor PDF supports additional built-in document attributes that impact PDF conversion. You can use these attributes to control the PDF media, launch mode, and outline, PDF optimization, text hyphenation, and various 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.

AsciiDoc document attributes

If an attribute is marked as "Header Only", it only takes effect if defined in the AsciiDoc document header or via the API. If an attribute matches a key in the theme file, the document attribute takes precedence.

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 hyphens attribute is set in the document, it overrides the base-hyphens key set in the theme. In other case, if the value is empty, then the value of the lang document attribute is used for 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. (Experimental) 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. For more fine-grained control, you should customize using the theme.

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