1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
= 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.
[cols="2,3,^1,6a"]
|===
|Attribute |Value Type |Header Only |Example
|`autofit-option`
|flag (default: _not set_)
|No
|`:autofit-option:`
|`<face>-cover-image`^[1]^
|path^[2]^ {vbar} image macro^[3]^ +
(format can be image or PDF)
|Yes
|`:front-cover-image: \image:front-cover.pdf[]`
|`hyphens`^[5]^
|language code {vbar} _blank_ to default to en_us (default: _not set_)
|Yes
|`:hyphens: de`
|xref:icons.adoc[icons]
|`font` {vbar} `image` (default: _not set_)
|No
|`:icons: font`
|`footnotes-title`
|String
|Yes
|`:footnotes-title: Endnotes`
|`index-pagenum-sequence-style`
|`term` {vbar} `page` {vbar} `range` (default: `term`)
|No
|`:index-pagenum-sequence-style: page`
|`media`
|`screen` {vbar} `print` {vbar} `prepress`
|Yes
|`:media: prepress`
|`compress`
|flag (default: _not set_)
|Yes
|`:compress:`
|`optimize`
|`screen` {vbar} `ebook` {vbar} `printer` {vbar} `prepress` {vbar} `default` (default: `default`)
|Yes
|`:optimize: prepress`
|xref:pdf-outline.adoc[outline]
|flag (default: _set_)
|Yes
|`:outline:`
|xref:pdf-outline.adoc#title[outline-title]
|flag {vbar} String (default: _set_)
|Yes
|`:outline-title: Outline`
|xref:pdf-outline.adoc#levels[outlinelevels]
|Integer {vbar} Integer:Integer (default: same as _toclevels_)
|Yes
|`:outlinelevels: 2`
|xref:background-images.adoc[page-background-image]
|path^[2]^ {vbar} image macro^[3]^
|Yes
|`:page-background-image: \image:bg.jpg[]`
|xref:background-images.adoc[page-background-image-(recto {vbar} verso)]
|path^[2]^ {vbar} image macro^[3]^
|Yes
|`:page-background-image-recto: \image:bg-recto.jpg[]`
|`page-foreground-image`
|path^[2]^ {vbar} image macro^[3]^
|Yes
|`:page-foreground-image: \image:watermark.svg[]`
|xref:page-numbers.adoc[pagenums]
|flag (default: _set_)
|Yes
|`:pagenums:`
|`pdf-page-layout`
|`portrait` {vbar} `landscape`
|Yes
|`:pdf-page-layout: landscape`
|`pdf-page-margin`
|xref:theme:measurement-units.adoc[Measurement] {vbar} xref:theme:measurement-units.adoc[Measurement[top,right,bottom,left\]]
|Yes
|`:pdf-page-margin: [1in, 0.5in]`
|`pdf-page-margin-rotated`
|xref:theme:measurement-units.adoc[Measurement] {vbar} xref:theme:measurement-units.adoc[Measurement[top,right,bottom,left\]]
|Yes
|`:pdf-page-margin-rotated: [0.5in, 0.25in]`
|`pdf-page-mode`
|`outline` {vbar} `none` {vbar} `thumbs` {vbar} `fullscreen` {vbar} `fullscreen outline` {vbar} `fullscreen none` {vbar} `fullscreen thumbs` (default: `outline`)
|Yes
|`:pdf-page-mode: fullscreen none`
|`pdf-page-size`
|https://github.com/prawnpdf/pdf-core/blob/0.6.0/lib/pdf/core/page_geometry.rb#L16-L68[Named size^] {vbar} xref:theme:measurement-units.adoc[Measurement[width, height\]]
|Yes
|`:pdf-page-size: [6in, 9in]`
|`pdf-folio-placement`
|`virtual` {vbar} `virtual-inverted` {vbar} `physical` {vbar} `physical-inverted`
|Yes
|`:pdf-folio-placement: physical`
|`pdf-version`
|`1.3` {vbar} `1.4` {vbar} `1.5` {vbar} `1.6` {vbar} `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]^
|xref:theme:text.adoc#text-align[Text alignment]
|Yes
|`:text-align: left`
|xref:title-page.adoc#logo[title-logo-image]
|path^[2]^ {vbar} image macro^[3]^
|Yes
|`:title-logo-image: \image:logo.png[top=25%, align=center, pdfwidth=0.5in]`
|xref:title-page.adoc[title-page]
|flag (default: _not set_)
|Yes
|`:title-page:`
|xref:title-page.adoc#background[title-page-background-image]
|path^[2]^ {vbar} 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 https://milan.kupcevic.net/ghostscript-ps-pdf/#marks[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. 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.
|
