You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1036 lines
23 KiB
1036 lines
23 KiB
4 years ago
|
////
|
||
|
|
Need to update the compatibility guide with:
|
||
|
|
|
||
|
|
* numbered = sectnums
|
||
|
|
* docinfo1 = docinfo
|
||
|
|
* docinfo2 = docinfo
|
||
|
|
* toc-class = use custom theme https://github.com/asciidoctor/asciidoctor.org/issues/379[issue #379]
|
||
|
|
* toc-placement = toc
|
||
|
|
* notitle = showtitle!
|
||
|
|
* encoding = ignored always UTF-8
|
||
|
|
|
||
|
|
////
|
||
|
|
[#builtin-attributes]
|
||
|
|
= Built-in Attributes
|
||
|
|
:y: icon:check[role="green"]
|
||
|
|
|
||
|
|
Built-in document attributes can be set anywhere in the document using an attribute entry line.
|
||
|
|
However, there are some rules to keep in mind regarding the impact of that assignment.
|
||
|
|
|
||
|
|
* Many attributes can only be defined in the <<doc-header,document header>> (or via the API or CLI).
|
||
|
|
Otherwise, they won't have the desired impact.
|
||
|
|
These are called _header attributes_.
|
||
|
|
This requirement is marked in the table below.
|
||
|
|
* To set an attribute that does not accept a value, simply use an empty value (as indicated by _empty_ in the table).
|
||
|
|
* If you set an attribute from the command line or API, it's defined for the whole document and cannot be changed in the body unless `@` is added to the end of the value.
|
||
|
|
(The one exception to this rule is the `sectnums` attribute, which can always be changed).
|
||
|
|
* If you set an attribute in the body (anywhere after the document header), the attribute is visible from the point it is set until it is unset (assuming it is not locked as a result of being set from the command line or API).
|
||
|
|
|
||
|
|
NOTE: Several attributes from AsciiDoc Python have been removed (or deprecated) in Asciidoctor and therefore are not included in this section.
|
||
|
|
See <<migrating-from-asciidoc-python>> if you are updating an older document.
|
||
|
|
|
||
|
|
[#builtin-attributes-table]
|
||
|
|
// tag::table[]
|
||
|
|
.Built-in document attributes
|
||
|
|
[cols="20,30,15,15,^5,15"]
|
||
|
|
|====
|
||
|
|
|Attribute name |Description |Default value^[1]^ |Allowed values |Header only |See also
|
||
|
|
|
||
|
|
6+<h|Compliance
|
||
|
|
|
||
|
|
|attribute-missing
|
||
|
|
|Controls how missing references are handled.
|
||
|
|
|skip
|
||
|
|
|skip, drop, drop-line or warn
|
||
|
|
|
|
||
|
|
|<<catch-a-missing-or-undefined-attribute>>
|
||
|
|
|
||
|
|
|attribute-undefined
|
||
|
|
|Controls how expressions that undefine an attribute are handled.
|
||
|
|
|drop-line
|
||
|
|
|drop or drop-line
|
||
|
|
|
|
||
|
|
|<<catch-a-missing-or-undefined-attribute>>
|
||
|
|
|
||
|
|
|compat-mode
|
||
|
|
|Controls whether the legacy parser is used to parse the document.
|
||
|
|
|_not set_ (Modern parser is used).
|
||
|
|
|_empty_ (Legacy parser is used).
|
||
|
|
|
|
||
|
|
|<<migrating-from-asciidoc-python>>
|
||
|
|
|
||
|
|
|experimental
|
||
|
|
|Enable experimental extensions.
|
||
|
|
The features behind this attribute are subject to change and may even be removed in a future version.
|
||
|
|
Currently enables the UI macros (button, menu and kbd).
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<user-interface-macros>>
|
||
|
|
|
||
|
|
|reproducible
|
||
|
|
|If set, prevents the last-updated date from being added to the HTML footer or DocBook info element.
|
||
|
|
Alternatively, you can use the SOURCE_DATE_EPOCH environment variable to fix the value.
|
||
|
|
Useful if you want to store the output in a source code control system as it prevents spurious changes every time you convert the document.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
6+<h|[[builtin-attributes-i18n]]Internationalization and numbering
|
||
|
|
|
||
|
|
|appendix-caption
|
||
|
|
|Sets the text used to prefix appendix titles.
|
||
|
|
|Appendix
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<user-appendix>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|appendix-number
|
||
|
|
|Stores the number (aka letter) for the current appendix.^[<<note_blocknum,2>>]^
|
||
|
|
|A
|
||
|
|
|_letter_
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
||
|
|
|appendix-refsig
|
||
|
|
|Sets the signifier added to the title of appendices in cross reference text.
|
||
|
|
Unset to disable.
|
||
|
|
|Appendix
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<book-parts-and-chapters>>, <<sections>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|caution-caption
|
||
|
|
|Sets the text used to label CAUTION admonitions when icons are not enabled.
|
||
|
|
|Caution
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<admonition>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|chapter-number
|
||
|
|
|Stores the number for the current chapter.^[<<note_blocknum,2>>]^
|
||
|
|
|2
|
||
|
|
|_integer_
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
||
|
|
|chapter-refsig
|
||
|
|
|Sets the signifier added to the title of numbered chapters in cross reference text.
|
||
|
|
Unset to disable.
|
||
|
|
|Chapter
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<book-parts-and-chapters>>, <<sections>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|chapter-label
|
||
|
|
|Sets the prefix added to chapter titles (i.e., level-1 section titles when doctype is book).
|
||
|
|
_(pdf converter only)_
|
||
|
|
|Chapter
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<book-parts-and-chapters>>, <<sections>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|example-caption
|
||
|
|
|Sets the text used to label example blocks.
|
||
|
|
|Example
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<customizing-labels>>
|
||
|
|
|
||
|
|
|example-number
|
||
|
|
|Stores the number for the current numbered example.^[<<note_blocknum,2>>]^
|
||
|
|
|5
|
||
|
|
|_integer_
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
||
|
|
|figure-caption
|
||
|
|
|Sets the text used to label figures.
|
||
|
|
|Figure
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<images>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|figure-number
|
||
|
|
|Stores the number for the current numbered figure.^[<<note_blocknum,2>>]^
|
||
|
|
|3
|
||
|
|
|_integer_
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
||
|
|
|important-caption
|
||
|
|
|Sets the text used to label IMPORTANT admonitions when icons are not enabled.
|
||
|
|
|Important
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<admonition>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|lang
|
||
|
|
|Set the value of the `lang` attribute on the root element of the output document.
|
||
|
|
|en
|
||
|
|
|Valid XML country code
|
||
|
|
|{y}
|
||
|
|
|<<customizing-labels>>
|
||
|
|
|
||
|
|
|last-update-label
|
||
|
|
|Text label for the “Last updated” time in the footer.
|
||
|
|
Unsetting it will remove the label and time from the footer.
|
||
|
|
|Last updated
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<footer-docinfo-files>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|listing-caption
|
||
|
|
|Sets the text used to label listing blocks.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<customizing-labels>>
|
||
|
|
|
||
|
|
|listing-number
|
||
|
|
|Stores the number for the current numbered listing.^[<<note_blocknum,2>>]^
|
||
|
|
|5
|
||
|
|
|_integer_
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
||
|
|
|manname-title
|
||
|
|
|Label for the program name section in the man page.
|
||
|
|
|NAME
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<customizing-labels>>
|
||
|
|
|
||
|
|
|nolang
|
||
|
|
|Prevents the `lang` attribute from being added to root element of the output document.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
|note-caption
|
||
|
|
|Sets the text used to label NOTE admonitions when icons are not enabled.
|
||
|
|
|Note
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<admonition>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|preface-title
|
||
|
|
|Sets the title text for an anonymous preface when the doctype is book.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<user-preface>>
|
||
|
|
|
||
|
|
|section-refsig
|
||
|
|
|Sets the signifier added to the title of numbered sections in cross reference text.
|
||
|
|
Unset to disable.
|
||
|
|
|Section
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<book-parts-and-chapters>>, <<sections>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|table-caption
|
||
|
|
|Text of the label that is automatically prefixed to table titles.
|
||
|
|
To turn off table caption labels and numbers, add the `table-caption` attribute to the document header with an empty value.
|
||
|
|
|Table
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<customizing-labels>>
|
||
|
|
|
||
|
|
|table-number
|
||
|
|
|Stores the number for the current numbered table.^[<<note_blocknum,2>>]^
|
||
|
|
|5
|
||
|
|
|_integer_
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
||
|
|
|tip-caption
|
||
|
|
|Sets the text used to label TIP admonitions when icons are not enabled.
|
||
|
|
|Tip
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<admonition>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|toc-title
|
||
|
|
|Title for the table of contents.
|
||
|
|
|Table of Contents
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<user-toc>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|untitled-label
|
||
|
|
|Used as the default document title if the document does not have a document title.
|
||
|
|
|Untitled
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<customizing-labels>>
|
||
|
|
|
||
|
|
|version-label
|
||
|
|
|The label preceding the revnumber in a converted document's byline
|
||
|
|
|Version
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<revision-number-date-and-remark>>, <<customizing-labels>>
|
||
|
|
|
||
|
|
|warning-caption
|
||
|
|
|Sets the text used to label TIP admonitions when icons are not enabled.
|
||
|
|
|Warning
|
||
|
|
|_any_
|
||
|
|
|
|
||
|
|
|<<customizing-labels>>
|
||
|
|
|
||
|
|
6+<h|Header and metadata
|
||
|
|
|
||
|
|
|app-name
|
||
|
|
|Application name (for mobile devices).
|
||
|
|
If set, adds an `application-name` meta element inside the HTML document head.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
|author
|
||
|
|
|Sets the document's main author.
|
||
|
|
Can be set automatically via the author info line.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|authorinitials
|
||
|
|
|Sets the author's initials (e.g., JD).
|
||
|
|
Derived automatically from the author attribute by default.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|authors
|
||
|
|
|Sets the document authors as a comma-separated list.
|
||
|
|
Can be set automatically via the author info line.
|
||
|
|
If set, adds an `author` meta element inside the HTML document head.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<metadata>>
|
||
|
|
|
||
|
|
|copyright
|
||
|
|
|If set, adds a `copyright` meta element inside the HTML document head.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<metadata>>
|
||
|
|
|
||
|
|
|doctitle
|
||
|
|
|Sets the document title.
|
||
|
|
Set automatically to section title if document begins with level-0 section.
|
||
|
|
|Based on content.
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<document-title>>
|
||
|
|
|
||
|
|
|description
|
||
|
|
|If set, adds a `description` meta element inside the HTML document head.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<metadata>>
|
||
|
|
|
||
|
|
|email
|
||
|
|
|Sets the author's email address.
|
||
|
|
Can be set automatically via the author info line.
|
||
|
|
Can be any inline macro, such as a URL.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|favicon
|
||
|
|
|Adds a link to a favicon to the HTML `<head>`.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<favicon>>
|
||
|
|
|
||
|
|
|firstname
|
||
|
|
|Sets the author's first name.
|
||
|
|
Can be set automatically via the author info line.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|front-matter
|
||
|
|
|If `skip-front-matter` is set via the CLI or API, any YAML-style frontmatter skimmed from the top of the document is stored in this attribute.
|
||
|
|
|Front matter content, if captured.
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<front-matter-added-for-static-site-generators>>
|
||
|
|
|
||
|
|
|keywords
|
||
|
|
|If set, adds a `keywords` meta element inside the HTML document head.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<metadata>>
|
||
|
|
|
||
|
|
|lastname
|
||
|
|
|Sets the author's last name.
|
||
|
|
Can be set automatically via the author info line.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|middlename
|
||
|
|
|Sets the author's middle name or initial.
|
||
|
|
Can be set automatically via the author info line.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|orgname
|
||
|
|
|If set, add an `<orgname>` element with this value to the DocBook info element.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<metadata>>
|
||
|
|
|
||
|
|
|revdate
|
||
|
|
|Sets the revision date.
|
||
|
|
Can be set automatically via the revision info line.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|revremark
|
||
|
|
|Sets the revision description.
|
||
|
|
Can be set automatically via the revision info line.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|revnumber
|
||
|
|
|Sets the revision number.
|
||
|
|
Can be set automatically via the revision info line.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|title
|
||
|
|
|Sets the value of the `<title>` element in the HTML `<head>` or main DocBook `<info>` of the output document.
|
||
|
|
Also used as a fallback when the document title is not specified.
|
||
|
|
_Since this is a reserved attribute that has special behavior, you should avoid using it for any other purpose!_
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<document-title>>
|
||
|
|
|
||
|
|
6+<h|Section titles and table of contents
|
||
|
|
|
||
|
|
|idprefix
|
||
|
|
|Sets prefix used for auto-generated section IDs.
|
||
|
|
|_
|
||
|
|
|Valid XML ID start character.
|
||
|
|
|{y}
|
||
|
|
|<<auto-generated-ids>>
|
||
|
|
|
||
|
|
|idseparator
|
||
|
|
|Sets word separator used in auto-generated section IDs.
|
||
|
|
|_
|
||
|
|
|Valid XML ID character.
|
||
|
|
|{y}
|
||
|
|
|<<auto-generated-ids>>
|
||
|
|
|
||
|
|
|leveloffset
|
||
|
|
|Pushes the level of subsequent headings down, to make file inclusion more useful.
|
||
|
|
|0
|
||
|
|
|(+/-)0{endash}5. (A leading + or - makes it relative).
|
||
|
|
|
|
||
|
|
|<<include-partitioning>>
|
||
|
|
|
||
|
|
|sectanchors
|
||
|
|
|If set, adds an anchor in front of the section title when the mouse cursor hovers over it.
|
||
|
|
|_not set_ (No anchors).
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<anchors>>
|
||
|
|
|
||
|
|
|sectids
|
||
|
|
|If set, generates and assigns an ID to any section that does not have one.
|
||
|
|
|_empty_ (Assigns section ID if not specified).
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<auto-generated-ids>>
|
||
|
|
|
||
|
|
|sectlinks
|
||
|
|
|Turns section titles into self-referencing links.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<links>>
|
||
|
|
|
||
|
|
|sectnums
|
||
|
|
|If set, numbers sections to depth specified by sectnumlevels.
|
||
|
|
|_not set_ (Sections are not numbered).
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<numbering>>
|
||
|
|
|
||
|
|
|sectnumlevels
|
||
|
|
|controls the depth of section numbering
|
||
|
|
|3
|
||
|
|
|0{endash}5
|
||
|
|
|{y}
|
||
|
|
|<<numbering-depth>>
|
||
|
|
|
||
|
|
|title-separator
|
||
|
|
|The character used to separate the main title and subtitle in the document title.
|
||
|
|
|:
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<subtitle-partitioning>>
|
||
|
|
|
||
|
|
|toc
|
||
|
|
|Switches the table of contents on, and defines its location.
|
||
|
|
|_not set_
|
||
|
|
|auto, left, right, macro or preamble
|
||
|
|
|{y}
|
||
|
|
|<<user-toc>>
|
||
|
|
|
||
|
|
|toclevels
|
||
|
|
|Maximum section level to display.
|
||
|
|
|2
|
||
|
|
|1{endash}5
|
||
|
|
|{y}
|
||
|
|
|<<user-toc>>
|
||
|
|
|
||
|
|
// NOTE toc-placement moved to deprecated table in migration guide
|
||
|
|
//|toc-placement
|
||
|
|
//|Location where table of contents is inserted.
|
||
|
|
//Should be treated as read-only.
|
||
|
|
//|Based on value of `toc` attribute.
|
||
|
|
//|auto, preamble, macro
|
||
|
|
//|{y}
|
||
|
|
//|<<user-toc>>
|
||
|
|
|
||
|
|
|fragment
|
||
|
|
|Hints to parser that document is a fragment and it should not enforce proper section nesting.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|
|
||
|
|
|
|
||
|
|
|
||
|
|
6+<h|General content and formatting
|
||
|
|
|
||
|
|
|asset-uri-scheme
|
||
|
|
|Controls which protocol is used for assets hosted on a CDN.
|
||
|
|
|https
|
||
|
|
|_empty_, http or https
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
|cache-uri
|
||
|
|
|If set, cache content read from URIs.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<caching-uri-content>>
|
||
|
|
|
||
|
|
|data-uri
|
||
|
|
|Embed graphics as data-uri elements in HTML elements so the file is completely self-contained.
|
||
|
|
|_not set_ (Images are linked, not embedded).
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<managing-images>>
|
||
|
|
|
||
|
|
|docinfo
|
||
|
|
|Read input from one or more DocBook info files.
|
||
|
|
|_not set_
|
||
|
|
|Comma-separated list of the following values: shared, private, shared-head, private-head, shared-footer or private-footer
|
||
|
|
|{y}
|
||
|
|
|<<naming-docinfo-files>>
|
||
|
|
|
||
|
|
|docinfodir
|
||
|
|
|The location where docinfo files are resolved.
|
||
|
|
|The base directory.
|
||
|
|
|Directory
|
||
|
|
|{y}
|
||
|
|
|<<locating-docinfo-files>>
|
||
|
|
|
||
|
|
|docinfosubs
|
||
|
|
|The AsciiDoc substitutions that get applied to docinfo content.
|
||
|
|
|attributes
|
||
|
|
|Comma-separated list of substitution names. Set value to empty or `none` to disable substitutions.
|
||
|
|
|{y}
|
||
|
|
|<<attribute-substitution-in-docinfo-files>>
|
||
|
|
|
||
|
|
|doctype
|
||
|
|
|Set the output document type.
|
||
|
|
|article
|
||
|
|
|article, book, inline or manpage
|
||
|
|
|{y}
|
||
|
|
|<<document-types>>
|
||
|
|
|
||
|
|
|eqnums
|
||
|
|
|Controls automatic equation numbering on LaTeX blocks in HTML output (MathJax).
|
||
|
|
If the value is AMS, only LaTeX content enclosed in an `\begin{equation}\...\end{equation}` container will be numbered.
|
||
|
|
If the value is all, then all LaTeX blocks will be numbered.
|
||
|
|
|_not set_ (Equation numbering is off)
|
||
|
|
|_empty_ (alias for AMS), AMS, all or none
|
||
|
|
|{y}
|
||
|
|
|<<stem>>, https://docs.mathjax.org/en/v2.5-latest/tex.html#automatic-equation-numbering[Equation numbering in MathJax]
|
||
|
|
|
||
|
|
|hardbreaks
|
||
|
|
|Preserve hard line breaks in the input.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|
|
||
|
|
|<<line-breaks>>
|
||
|
|
|
||
|
|
|hide-uri-scheme
|
||
|
|
|Hides the URI scheme for all raw links.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|
|
||
|
|
|<<url>>
|
||
|
|
|
||
|
|
|linkattrs
|
||
|
|
|Parse attributes inside the link macro.
|
||
|
|
Removed in Asciidoctor 1.5.7.
|
||
|
|
Attributes are now parsed automatically if an equal sign is found after a comma (e.g., `[link text,window=_blank]`).
|
||
|
|
|_not set_ (Do not parse).
|
||
|
|
|_empty_
|
||
|
|
|
|
||
|
|
|<<url>>
|
||
|
|
|
||
|
|
|media
|
||
|
|
|Specifies the media type of the output, which may enable behavior specific to that media type.
|
||
|
|
|_screen_
|
||
|
|
|screen or print
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
|nofooter
|
||
|
|
|Suppresses output of the footer.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<footer-docinfo-files>>
|
||
|
|
|
||
|
|
|nofootnotes
|
||
|
|
|Turn off display of footnotes.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<user-footnotes>>
|
||
|
|
|
||
|
|
|noheader
|
||
|
|
|Suppresses output of the header.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<doc-header>>
|
||
|
|
|
||
|
|
|outfilesuffix
|
||
|
|
|File extension of the output file (starting with a period).
|
||
|
|
|Determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc).
|
||
|
|
|File extension
|
||
|
|
|
|
||
|
|
|<<navigating-between-source-files>>
|
||
|
|
|
||
|
|
|pagewidth
|
||
|
|
|Page width, used to calculate the absolute width of tables in the DocBook output.
|
||
|
|
|425
|
||
|
|
|Number
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
|relfileprefix
|
||
|
|
|The path prefix to add to relative xrefs.
|
||
|
|
|_empty_
|
||
|
|
|Path segment
|
||
|
|
|
|
||
|
|
|<<navigating-between-source-files>>
|
||
|
|
|
||
|
|
|show-link-uri
|
||
|
|
|Prints the URI of a link after the linked text.
|
||
|
|
_(pdf converter only)_
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
|showtitle
|
||
|
|
|If set, displays an embedded document's title.
|
||
|
|
Mutually exclusive with the `notitle` attribute.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<document-title>>
|
||
|
|
|
||
|
|
|stem
|
||
|
|
|Enables mathematics processing or sets the processor used.
|
||
|
|
|_not set_
|
||
|
|
|_empty_ (defaults to asciimath), asciimath or latexmath
|
||
|
|
|{y}
|
||
|
|
|<<stem-in>>
|
||
|
|
|
||
|
|
|tabsize
|
||
|
|
|If set, converts tabs to spaces in verbatim content blocks (e.g., listing, literal).
|
||
|
|
|_not set_
|
||
|
|
|0 or more
|
||
|
|
|
|
||
|
|
|-
|
||
|
|
|
||
|
|
|webfonts
|
||
|
|
|Control whether webfonts are loaded, and which ones, when using the default stylesheet.
|
||
|
|
The value populates the `family` query string parameter in the Google Fonts URL.
|
||
|
|
|_empty_ (use default fonts)
|
||
|
|
|_empty_ or a Google Fonts collection spec
|
||
|
|
|{y}
|
||
|
|
|<<applying-a-theme>> and https://github.com/asciidoctor/asciidoctor.org/issues/410[issue #410]
|
||
|
|
|
||
|
|
|xmlns
|
||
|
|
|The XML namespace to add to the DocBook 4.5 document. (The DocBook 5 document always declares a namespace).
|
||
|
|
|_not set_
|
||
|
|
|_empty_ (alias for the DocBook namespace) or a valid XML namespace.
|
||
|
|
|{y}
|
||
|
|
|<<docbook>>
|
||
|
|
|
||
|
|
|xrefstyle
|
||
|
|
|The formatting style to apply to cross reference text.
|
||
|
|
_Introduced in 1.5.6._
|
||
|
|
|_not set_
|
||
|
|
|full, short, or basic
|
||
|
|
|{y}
|
||
|
|
|<<customizing-the-cross-reference-text>>
|
||
|
|
|
||
|
|
6+<h|Images and icons
|
||
|
|
|
||
|
|
|iconfont-cdn
|
||
|
|
|Overrides the CDN used to resolve the Font Awesome stylesheet.
|
||
|
|
Only used when `icons` attribute is set to `font`.
|
||
|
|
|cdnjs
|
||
|
|
|URI
|
||
|
|
|{y}
|
||
|
|
|<<icons>>
|
||
|
|
|
||
|
|
|iconfont-name
|
||
|
|
|Overrides the name of the icon font stylesheet.
|
||
|
|
Only used when `icons` attribute is set to `font`.
|
||
|
|
|font-awesome
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<icons>>
|
||
|
|
|
||
|
|
|iconfont-remote
|
||
|
|
|If set, allows use of a CDN for resolving the icon font.
|
||
|
|
Only used when `icons` attribute is set to `font`.
|
||
|
|
|_empty_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<icons>>
|
||
|
|
|
||
|
|
|icons
|
||
|
|
|Chooses icons instead of text for admonitions.
|
||
|
|
|_not set_ (image)
|
||
|
|
|font or image
|
||
|
|
|{y}
|
||
|
|
|<<icons>>
|
||
|
|
|
||
|
|
|iconsdir
|
||
|
|
|Where icons are stored.
|
||
|
|
Only used when `icons` attribute is set to `image`.
|
||
|
|
|\{imagesdir}/icons (or ./images/icons if imagesdir is not set)
|
||
|
|
|Directory
|
||
|
|
|{y}
|
||
|
|
|<<icons>>
|
||
|
|
|
||
|
|
|icontype
|
||
|
|
|File type for image icons.
|
||
|
|
Only used when `icons` attribute is set to `image`.
|
||
|
|
|png
|
||
|
|
|any, but typically jpg, tiff, etc.
|
||
|
|
|{y}
|
||
|
|
|<<icons>>
|
||
|
|
|
||
|
|
|imagesdir
|
||
|
|
|Where image files are resolved.
|
||
|
|
|_not set_ (Same directory as document).
|
||
|
|
|Directory
|
||
|
|
|
|
||
|
|
|<<images>>
|
||
|
|
|
||
|
|
6+<h|Code highlighting and formatting
|
||
|
|
|
||
|
|
|coderay-css
|
||
|
|
|Controls whether CodeRay uses CSS classes or inline styles.
|
||
|
|
|class
|
||
|
|
|class or style
|
||
|
|
|{y}
|
||
|
|
|<<coderay>>
|
||
|
|
|
||
|
|
|coderay-linenums-mode
|
||
|
|
|Sets how CodeRay inserts line numbers into source listings.
|
||
|
|
|table
|
||
|
|
|table or inline
|
||
|
|
|{y}
|
||
|
|
|<<coderay>>
|
||
|
|
|
||
|
|
|coderay-unavailable
|
||
|
|
|If set, tells the processor not to attempt to load CodeRay.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<coderay>>
|
||
|
|
|
||
|
|
|highlightjsdir
|
||
|
|
|Location of the highlight.js source code highlighter library.
|
||
|
|
|_not set_
|
||
|
|
|Directory
|
||
|
|
|{y}
|
||
|
|
|<<highlight-js>>
|
||
|
|
|
||
|
|
|highlightjs-theme
|
||
|
|
|Sets the name of the theme used by the highlight.js source code highlighter.
|
||
|
|
|github
|
||
|
|
|A style name recognized by highlight.js.
|
||
|
|
|{y}
|
||
|
|
|<<highlight-js>>
|
||
|
|
|
||
|
|
|prettifydir
|
||
|
|
|Location of the prettify source code highlighter library.
|
||
|
|
|_not set_ (Uses CDN).
|
||
|
|
|Directory
|
||
|
|
|{y}
|
||
|
|
|<<source-code-blocks>>
|
||
|
|
|
||
|
|
|prettify-theme
|
||
|
|
|Sets the name of the theme used by the prettify source code highlighter.
|
||
|
|
|prettify
|
||
|
|
|A style name recognized by prettify.
|
||
|
|
|{y}
|
||
|
|
|<<source-code-blocks>>
|
||
|
|
|
||
|
|
|prewrap
|
||
|
|
|Wrap wide code listings.
|
||
|
|
Sets the default behavior only; you can still switch off wrapping on specific listings.
|
||
|
|
|_empty_ (Code listing will wrap long lines, not scroll).
|
||
|
|
|_empty_
|
||
|
|
|
|
||
|
|
|<<to-wrap-or-to-scroll>>
|
||
|
|
|
||
|
|
|pygments-css
|
||
|
|
|Controls whether Pygments uses CSS classes or inline styles.
|
||
|
|
|class
|
||
|
|
|class or style
|
||
|
|
|{y}
|
||
|
|
|<<pygments>>
|
||
|
|
|
||
|
|
|pygments-linenums-mode
|
||
|
|
|Sets how Pygments inserts line numbers into source listings.
|
||
|
|
|table
|
||
|
|
|table or inline
|
||
|
|
|{y}
|
||
|
|
|<<pygments>>
|
||
|
|
|
||
|
|
|pygments-style
|
||
|
|
|Sets the name of the style used by the Pygments source code highlighter
|
||
|
|
|default
|
||
|
|
|A style name recognized by Pygments.
|
||
|
|
|{y}
|
||
|
|
|<<pygments>>
|
||
|
|
|
||
|
|
|pygments-unavailable
|
||
|
|
|If set, tells the processor not to attempt to load Pygments.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<pygments>>
|
||
|
|
|
||
|
|
|source-highlighter
|
||
|
|
|Source code highlighter to use.
|
||
|
|
|_not set_
|
||
|
|
|coderay, highlightjs, prettify or pygments
|
||
|
|
|{y}
|
||
|
|
|<<source-code-blocks>>
|
||
|
|
|
||
|
|
|source-indent
|
||
|
|
|Normalize block indentation in code listings.
|
||
|
|
|_not set_ (Indentation is not modified).
|
||
|
|
|Number
|
||
|
|
|
|
||
|
|
|<<normalize-block-indentation>>
|
||
|
|
|
||
|
|
|source-language
|
||
|
|
|Set the default language for source code listings.
|
||
|
|
|_not set_
|
||
|
|
|Code language name in lowercase.
|
||
|
|
|
|
||
|
|
|<<source-code-blocks>>
|
||
|
|
|
||
|
|
|source-linenums-option
|
||
|
|
|Turns on line numbers option by default for source code listings.
|
||
|
|
_Introduced in 1.5.6._
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|
|
||
|
|
|<<source-code-blocks>>
|
||
|
|
|
||
|
|
6+<h|HTML styling
|
||
|
|
|
||
|
|
|copycss
|
||
|
|
|If set, copy the CSS files to the output.
|
||
|
|
|_empty_ (File is copied if `linkcss` is set).
|
||
|
|
|Empty or the location of the custom stylesheet (if used)
|
||
|
|
|{y}
|
||
|
|
|<<applying-a-theme>>
|
||
|
|
|
||
|
|
|css-signature
|
||
|
|
|If set, assign the value to the `id` attribute of the `<body>` element (HTML only).
|
||
|
|
The preferred approach is to assign an ID to the document title.
|
||
|
|
|_not set_
|
||
|
|
|Valid XML ID
|
||
|
|
|{y}
|
||
|
|
// TODO link to <<document-title>> once it covers ID assignment
|
||
|
|
|
|
||
|
|
|
||
|
|
|linkcss
|
||
|
|
|If set, link to the stylesheet instead of embedding it.
|
||
|
|
Cannot be unset in SECURE safe mode.
|
||
|
|
|_not set_ (when safe mode < SECURE) +
|
||
|
|
_set_ (when safe mode is SECURE)
|
||
|
|
|_empty_
|
||
|
|
|{y}
|
||
|
|
|<<styling-the-html-with-css>>
|
||
|
|
|
||
|
|
|max-width
|
||
|
|
|Constrain the maximum width of the document body.
|
||
|
|
*Not recommended.
|
||
|
|
Use custom CSS instead.*
|
||
|
|
|_not set_
|
||
|
|
|CSS length (e.g. 55em, 12cm, etc)
|
||
|
|
|{y}
|
||
|
|
|
|
||
|
|
|
||
|
|
|stylesdir
|
||
|
|
|Location for resolving CSS stylesheets.
|
||
|
|
|. (Same directory as document).
|
||
|
|
|Directory
|
||
|
|
|{y}
|
||
|
|
|<<creating-a-theme>>
|
||
|
|
|
||
|
|
|stylesheet
|
||
|
|
|Name of a CSS stylesheet to replace the default one.
|
||
|
|
|_not set_ (The default stylesheet is used).
|
||
|
|
|File name
|
||
|
|
|{y}
|
||
|
|
|<<applying-a-theme>>
|
||
|
|
|
||
|
|
|toc-class
|
||
|
|
|The CSS class on the table of contents container.
|
||
|
|
|toc
|
||
|
|
|Valid CSS class name
|
||
|
|
|{y}
|
||
|
|
|<<user-toc>>
|
||
|
|
|
||
|
|
6+<h|Manpage attributes (relevant only when using the manpage doctype and/or converter)
|
||
|
|
|
||
|
|
|mantitle
|
||
|
|
|Metadata for manpage output.
|
||
|
|
|Based on content.
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<man-pages>>
|
||
|
|
|
||
|
|
|manvolnum
|
||
|
|
|Metadata for manpage output.
|
||
|
|
|Based on content.
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<man-pages>>
|
||
|
|
|
||
|
|
|manname
|
||
|
|
|Metadata for manpage output.
|
||
|
|
|Based on content.
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<man-pages>>
|
||
|
|
|
||
|
|
|manpurpose
|
||
|
|
|Metadata for manpage output.
|
||
|
|
|Based on content.
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<man-pages>>
|
||
|
|
|
||
|
|
|man-linkstyle
|
||
|
|
|Style the links in the manpage output.
|
||
|
|
|blue R <>
|
||
|
|
|Link format sequence
|
||
|
|
|{y}
|
||
|
|
|<<man-pages>>
|
||
|
|
|
||
|
|
|mansource
|
||
|
|
|The source (e.g., application and version) to which the man page pertains.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<man-pages>>
|
||
|
|
|
||
|
|
|manmanual
|
||
|
|
|Manual name displayed in the man page footer.
|
||
|
|
|_not set_
|
||
|
|
|_any_
|
||
|
|
|{y}
|
||
|
|
|<<man-pages>>
|
||
|
|
|
||
|
|
6+<h|Secure attributes (can only be set from the command line or API, typically for security reasons)
|
||
|
|
|
||
|
|
|allow-uri-read
|
||
|
|
|If set, allows data to be read from URIs (via include directive, image macro when embedding images, etc.).
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|CLI or API
|
||
|
|
|<<include-uri>>
|
||
|
|
|
||
|
|
|max-attribute-value-size
|
||
|
|
|Limits the maximum size (in bytes) of a resolved attribute value.
|
||
|
|
Since attributes can reference other attributes, it would be possible to create an output document disproportionately larger than the input document without this limit in place.
|
||
|
|
|4096 (secure mode), _not set_ (other modes)
|
||
|
|
|0 or greater
|
||
|
|
|CLI or API
|
||
|
|
|
|
||
|
|
|
||
|
|
|max-include-depth
|
||
|
|
|Safety feature to curtail infinite include loops and to limit the opportunity to exploit nested includes to compound the size of the output document.
|
||
|
|
|64
|
||
|
|
|0 or greater
|
||
|
|
|CLI or API
|
||
|
|
|<<include-directive>>
|
||
|
|
|
||
|
|
|skip-front-matter
|
||
|
|
|If set, consume YAML-style frontmatter at the top of the document and store it in the `front-matter` attribute.
|
||
|
|
|_not set_
|
||
|
|
|_empty_
|
||
|
|
|CLI or API
|
||
|
|
|<<front-matter-added-for-static-site-generators>>
|
||
|
|
|====
|
||
|
|
|
||
|
|
^[1]^ The default value isn't necessarily the value you will get by entering `\{name}`.
|
||
|
|
It may be the fallback value which Asciidoctor uses if the attribute is not defined.
|
||
|
|
The effect is the same either way.
|
||
|
|
|
||
|
|
[[note_blocknum]]^[2]^ The `-number` attributes are created and managed automatically by Asciidoctor for numbered blocks.
|
||
|
|
They are only used if the corresponding `-caption` attribute is set (e.g., `listing-caption`) and the block has a title.
|
||
|
|
In the current version of Asciidoctor, setting the `-number` attributes will influence the number used for subsequent numbered blocks of that type.
|
||
|
|
However, you should not rely on this behavior as it may change in future versions.
|
||
|
|
// end::table[]
|