1 files changed, 172 insertions, 0 deletions
diff --git a/docs/modules/theme/pages/asciidoc-attributes.adoc b/docs/modules/theme/pages/asciidoc-attributes.adoc
new file mode 100644
index 00000000..9c4c6b61
--- /dev/null
+++ b/docs/modules/theme/pages/asciidoc-attributes.adoc
@@ -0,0 +1,172 @@
+= 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,6l"]
+|===
+|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
+
+|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
+
+|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:measurement-units.adoc[Measurement] {vbar} xref: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: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:text.adoc#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-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:admonition.adoc#key-prefix-admonition-icon[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.