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
|
= Theme-Related AsciiDoc Attributes
There are various settings in the theme you control using document attributes.
== 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 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`^[7]^
|language code {vbar} _blank_ to default to en_us (default: _not set_)
|Yes
|`:hyphens: de`
|`icons`^[13]^
|`font` {vbar} image (default: _not set_)
|No
|`:icons: font`
|`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`
|`outline-title`
|flag {vbar} String (default: _set_)
|Yes
|`:outline-title: Outline`
|`outlinelevels`^[12]^
|Integer {vbar} Integer:Integer (default: same as _toclevels_)
|Yes
|`:outlinelevels: 2`
|`page-background-image`^[4]^
|path^[2]^ {vbar} image macro^[3]^
|Yes
|`:page-background-image: \image:bg.jpg[]`
|`page-background-image-`(`recto`{vbar}`verso`)^[4]^
|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[]`
|`pagenums`^[5]^
|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-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`^[6]^
|flag (default: _not set_)
|Yes
|`:pdfmark:`
|`scripts`^[8]^
|`cjk` (default: _not set_)
|Yes
|`:scripts: cjk`
|`text-align`^[9]^
|xref:theme:text.adoc#text-align[Text alignment]
|Yes
|`:text-align: left`
|`title-logo-image`
|path^[2]^ {vbar} image macro^[3]^
|Yes
|`:title-logo-image: \image:logo.png[top=25%, align=center, pdfwidth=0.5in]`
|`title-page`^[10]^
|flag (default: _not set_)
|Yes
|`:title-page:`
|`title-page-background-image`
|path^[2]^ {vbar} image macro^[3]^
|Yes
|`:title-page-background-image: \image:title-bg.jpg[]`
|`toc-max-pagenum-digits`^[11]^
|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. 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.
If the recto (right-hand, odd-numbered pages) or verso (left-hand, even-numbered pages) background is specified, it will be used only for that side.
If a background image isn't specified for a side, the converter will use the default page background image (`page-background-image`), if specified.
To disable the background image for a side, use the value `none`.
5. Controls whether the implicit `page-number` attribute is to the running header and footer content specified in the theme file.
Instead of disabling page numbers, you can use the `noheader` and `nofooter` attributes to disable the running header and footer, respectively.
6. 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.
7. Activates hyphenation for the language code specified (defaults to en_us).
8. 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.
9. _(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.
10. The title page is only enabled by default for the book doctype.
To force the title page to be used for other doctypes, set the `title-page` attribute in the document header.
11. If the TOC overlaps the first page of content, increase this number.
12. The second number in the value of `outlinelevels` is the number of levels of the outline to expand (e.g., `3:1`).
If the second number is not present, all levels are expanded.
13. By default, admonitions have a text-based label that matches the admonition type.
To use icons instead, set the `icons` attribute to `font`.
This setting allows the theme to control the icon used for each type (see the xref:theme:admonition.adoc#icon-name[admonition-icon key]).
It also enables the `icon` macro (covered in the README).
To use local image files, set the `icons` attribute to `image`.
Note that if the value of the `icons` attribute is `image`, the `icon` macro will produce text-based output.
|
