Appendix A: Catalog of Document Attributes
This appendix catalogs all the recognized document attributes in Asciidoctor. It includes environment, built-in and predefined (aka character reference) attributes. Authors may define any number of additional attributes (aka user-defined attributes) for their own purposes.
A.1. Environment Attributes
Asciidoctor automatically assigns values to various document attributes whenever a document is loaded or converted. These attributes, termed environment attributes, provide information about the runtime environment, such as how, where and when the document is being processed. Like other document attributes, environment attributes can be referenced whereever attribute references are permitted. It’s recommended that you treat these attributes as read only.
Attribute | Description | Example Value |
---|---|---|
|
Set if the current processor is Asciidoctor. |
|
|
Asciidoctor version. |
|
|
Backend used to create the output file. |
|
|
The backend value minus any trailing numbers.
For example, if the backend is |
|
|
|
|
|
|
|
|
Full path of the directory that contains the source document. |
|
|
Full path of the source document. |
|
|
File extension of the source document, including the leading period. Introduced in 1.5.6. |
|
|
Root name of the source document (no leading path or file extension). |
|
|
|
|
|
Document type (article, book or manpage). |
|
|
Year that the document was last modified.[1,2] |
|
|
Set if content is being converted to an embeddable document (body only). |
|
|
File extension of the output file name (without leading period). |
|
|
Syntax used when generating the HTML output (html or xhtml). |
|
|
Date when the document was converted.[2] |
|
|
Date and time when the document was converted.[2] |
|
|
Time when the document was converted.[2] |
|
|
Year when the document was converted.[2] |
|
|
Full path of the output directory. |
|
|
Full path of the output file. |
|
|
File extension of the output file (starting with a period) as determined by the backend ( |
|
|
Numeric value of the safe mode setting. (UNSAFE=0, SAFE=10, SERVER=10, SECURE=20). |
|
|
Textual value of the safe mode setting. |
|
|
Set if the safe mode is UNSAFE. |
|
|
Set if the safe mode is SAFE. |
|
|
Set if the safe mode is SERVER. |
|
|
Set if the safe mode is SECURE. |
|
|
Home directory of the current user.
Resolves to |
|
[1] Only reflects the last modified time of the source document file. It does not consider the last modified time of files which are included.
[2] If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that corresponds to the timestamp (as an integer) stored in that environment variable. This override offers one way to make the conversion reproducible. See https://reproducible-builds.org/specs/source-date-epoch/ for more information about the SOURCE_DATE_EPOCH environment variable.
A.2. Built-in Attributes
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 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 commandline 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 thesectnums
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 commandline or API).
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. |
Attribute name | Description | Default value[1] | Allowed values | Header only | See also |
---|---|---|---|---|---|
Compliance |
|||||
attribute-missing |
Controls how missing references are handled. |
skip |
skip, drop, drop-line or warn |
||
attribute-undefined |
Controls how expressions that undefine an attribute are handled. |
drop-line |
drop or drop-line |
||
compat-mode |
Controls whether the legacy parser is used to parse the document. |
not set (Modern parser is used). |
empty (Legacy parser is used). |
||
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 |
||
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 |
||
appendix-caption |
Sets the text used to prefix appendix titles. |
Appendix |
any |
||
appendix-number |
Stores the number (aka letter) for the current appendix.[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, Translating built-in labels |
|
caution-caption |
Sets the text used to label CAUTION admonitions when icons are not enabled. |
Caution |
any |
||
chapter-number |
Stores the number for the current chapter.[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, Translating built-in 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, Translating built-in labels |
|
example-caption |
Sets the text used to label example blocks. |
Example |
any |
||
example-number |
Stores the number for the current numbered example.[2] |
5 |
integer |
||
figure-caption |
Sets the text used to label figures. |
Figure |
any |
||
figure-number |
Stores the number for the current numbered figure.[2] |
3 |
integer |
||
important-caption |
Sets the text used to label IMPORTANT admonitions when icons are not enabled. |
Important |
any |
||
lang |
Set the value of the |
en |
Valid XML country code |
||
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 |
||
listing-caption |
Sets the text used to label listing blocks. |
not set |
any |
||
listing-number |
Stores the number for the current numbered listing.[2] |
5 |
integer |
||
manname-title |
Label for the program name section in the manpage. |
NAME |
any |
||
nolang |
Prevents the |
not set |
empty |
||
note-caption |
Sets the text used to label NOTE admonitions when icons are not enabled. |
Note |
any |
||
preface-title |
Sets the title text for an anonymous preface when the doctype is book. |
not set |
any |
||
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, Translating built-in 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 |
any |
||
table-number |
Stores the number for the current numbered table.[2] |
5 |
integer |
||
tip-caption |
Sets the text used to label TIP admonitions when icons are not enabled. |
Tip |
any |
||
toc-title |
Title for the table of contents. |
Table of Contents |
any |
||
untitled-label |
Used as the default document title if the document does not have a document title. |
Untitled |
any |
||
version-label |
The label preceding the revnumber in a converted document’s byline |
Version |
any |
Revision Number, Date and Remark, Translating built-in labels |
|
warning-caption |
Sets the text used to label TIP admonitions when icons are not enabled. |
Warning |
any |
||
Header and metadata |
|||||
app-name |
Application name (for mobile devices).
If set, adds an |
not set |
any |
||
author |
Sets the document’s main author. Can be set automatically via the author info line. |
not set |
any |
||
authorinitials |
Sets the author’s initials (e.g., JD). Derived automatically from the author attribute by default. |
not set |
any |
||
authors |
Sets the document authors as a comma-separated list.
Can be set automatically via the author info line.
If set, adds an |
not set |
any |
||
copyright |
If set, adds a |
not set |
any |
||
doctitle |
Sets the document title. Set automatically to section title if document begins with level-0 section. |
Based on content. |
any |
||
description |
If set, adds a |
not set |
any |
||
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 |
|||
firstname |
Sets the author’s first name. Can be set automatically via the author info line. |
not set |
any |
||
front-matter |
If |
Front matter content, if captured. |
any |
||
keywords |
If set, adds a |
not set |
any |
||
lastname |
Sets the author’s last name. Can be set automatically via the author info line. |
not set |
any |
||
middlename |
Sets the author’s middle name or initial. Can be set automatically via the author info line. |
not set |
any |
||
orgname |
If set, add an |
not set |
any |
||
revdate |
Sets the revision date. Can be set automatically via the revision info line. |
not set |
any |
||
revremark |
Sets the revision description. Can be set automatically via the revision info line. |
not set |
any |
||
revnumber |
Sets the revision number. Can be set automatically via the revision info line. |
not set |
any |
||
title |
Sets the value of the |
not set |
any |
||
Section titles and table of contents |
|||||
idprefix |
Sets prefix used for auto-generated section IDs. |
_ |
Valid XML ID start character. |
||
idseparator |
Sets word separator used in auto-generated section IDs. |
_ |
Valid XML ID character. |
||
leveloffset |
Pushes the level of subsequent headings down, to make file inclusion more useful. |
0 |
(+/-)0–5. (A leading + or - makes it relative). |
||
sectanchors |
If set, adds an anchor in front of the section title when the mouse cursor hovers over it. |
not set (No anchors). |
empty |
||
sectids |
If set, generates and assigns an ID to any section that does not have one. |
empty (Assigns section ID if not specified). |
empty |
||
sectlinks |
Turns section titles into self-referencing links. |
not set |
empty |
||
sectnums |
If set, numbers sections to depth specified by sectnumlevels. |
not set (Sections are not numbered). |
empty |
||
sectnumlevels |
controls the depth of section numbering |
3 |
0–5 |
||
title-separator |
The character used to separate the main title and subtitle in the document title. |
: |
any |
||
toc |
Switches the table of contents on, and defines its location. |
not set |
auto, left, right, macro or preamble |
||
toclevels |
Maximum section level to display. |
2 |
1–5 |
||
fragment |
Hints to parser that document is a fragment and it should not enforce proper section nesting. |
not set |
empty |
||
General content and formatting |
|||||
asset-uri-scheme |
Controls which protocol is used for assets hosted on a CDN. |
https |
empty, http or https |
||
cache-uri |
If set, cache content read from URIs. |
not set |
empty |
||
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 |
||
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 |
||
docinfodir |
The location where docinfo files are resolved. |
The base directory. |
Directory |
||
docinfosubs |
The AsciiDoc substitutions that get applied to docinfo content. |
attributes |
Comma-separated list of substitution names. Set value to empty or |
||
doctype |
Set the output document type. |
article |
article, book, inline or manpage |
||
eqnums |
Controls automatic equation numbering on LaTeX blocks in HTML output (MathJax). |
not set (Equation numbering is off) |
empty (alias for AMS), AMS, all or none |
||
hardbreaks |
Preserve hard line breaks in the input. |
not set |
empty |
||
hide-uri-scheme |
Hides the URI scheme for all raw links. |
not set |
empty |
||
linkattrs |
Parse attributes inside the link macro. |
not set (Do not parse). |
empty |
||
media |
Specifies the media type of the output, which may enable behavior specific to that media type. |
screen |
screen or print |
||
nofooter |
Suppresses output of the footer. |
not set |
empty |
||
nofootnotes |
Turn off display of footnotes. |
not set |
empty |
||
noheader |
Suppresses output of the header. |
not set |
empty |
||
outfilesuffix |
File extension of the output file (starting with a period). |
Determined by the backend ( |
File extension |
||
pagewidth |
Page width, used to calculate the absolute width of tables in the DocBook output. |
425 |
Number |
||
relfileprefix |
The path prefix to add to relative xrefs. |
empty |
Path segment |
||
show-link-uri |
Prints the URI of a link after the linked text. (pdf converter only) |
not set |
empty |
||
showtitle |
If set, displays an embedded document’s title.
Mutually exclusive with the |
not set |
empty |
||
stem |
Enables mathematics processing or sets the processor used. |
not set |
empty (defaults to asciimath), asciimath or latexmath |
||
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 |
empty (use default fonts) |
empty or a Google Fonts collection spec |
||
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. |
||
xrefstyle |
The formatting style to apply to cross reference text. Introduced in 1.5.6. |
not set |
full, short, or basic |
||
Images and icons |
|||||
iconfont-cdn |
Overrides the CDN used to resolve the Font Awesome stylesheet.
Only used when |
cdnjs |
URI |
||
iconfont-name |
Overrides the name of the icon font stylesheet.
Only used when |
font-awesome |
any |
||
iconfont-remote |
If set, allows use of a CDN for resolving the icon font.
Only used when |
empty |
empty |
||
icons |
Chooses icons instead of text for admonitions. |
not set (image) |
font or image |
||
iconsdir |
Where icons are stored.
Only used when |
{imagesdir}/icons (or ./images/icons if imagesdir is not set) |
Directory |
||
icontype |
File type for image icons.
Only used when |
png |
any, but typically jpg, tiff etc. |
||
imagesdir |
Where image files are resolved. |
not set (Same directory as document). |
Directory |
||
Code highlighting and formatting |
|||||
coderay-css |
Controls whether CodeRay uses CSS classes or inline styles. |
class |
class or style |
||
coderay-linenums-mode |
Sets how Coderay inserts line numbers into source listings. |
table |
table or inline |
||
coderay-unavailable |
If set, tells the processor not to attempt to load CodeRay. |
not set |
empty |
||
highlightjsdir |
Location of the highlight.js source code highlighter library. |
not set |
Directory |
||
highlightjs-theme |
Sets the name of the theme used by the highlight.js source code highlighter. |
github |
A style name recognized by highlight.js. |
||
prettifydir |
Location of the prettify source code highlighter library. |
not set (Uses CDN). |
Directory |
||
prettify-theme |
Sets the name of the theme used by the prettify source code highlighter. |
prettify |
A style name recognized by prettify. |
||
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 |
||
pygments-css |
Controls whether Pygments uses CSS classes or inline styles. |
class |
class or style |
||
pygments-linenums-mode |
Sets how Pygments inserts line numbers into source listings. |
table |
table or inline |
||
pygments-style |
Sets the name of the style used by the Pygments source code highlighter |
default |
A style name recognized by Pygments. |
||
pygments-unavailable |
If set, tells the processor not to attempt to load Pygments. |
not set |
empty |
||
source-highlighter |
Source code highlighter to use. |
not set |
coderay, highlightjs, prettify or pygments |
||
source-indent |
Normalize block indentation in code listings. |
not set (Indentation is not modified). |
Number |
||
source-language |
Set the default language for source code listings. |
not set |
Code language name in lowercase. |
||
source-linenums-option |
Turns on line numbers option by default for source code listings. Introduced in 1.5.6. |
not set |
empty |
||
HTML styling |
|||||
copycss |
If set, copy the CSS files to the output. |
empty (File is copied if |
empty |
||
css-signature |
If set, assign the value to the |
not set |
Valid XML ID |
||
linkcss |
If set, link to the stylesheet instead of embedding it. Cannot be unset in SECURE safe mode. |
not set (when safe mode < SECURE) |
empty |
||
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) |
||
stylesdir |
Location for resolving CSS stylesheets. |
. (Same directory as document). |
Directory |
||
stylesheet |
Name of a CSS stylesheet to replace the default one. |
not set (The default stylesheet is used). |
File name |
||
toc-class |
The CSS class on the table of contents container. |
toc |
Valid CSS class name |
||
Manpage attributes (relevant only when using the manpage doctype and/or converter) |
|||||
mantitle |
Metadata for manpage output. |
Based on content. |
any |
||
manvolnum |
Metadata for manpage output. |
Based on content. |
any |
||
manname |
Metadata for manpage output. |
Based on content. |
any |
||
manpurpose |
Metadata for manpage output. |
Based on content. |
any |
||
man-linkstyle |
Style the links in the manpage output. |
blue R <> |
Link format sequence |
||
mansource |
The source (e.g., application and version) to which the manpage pertains. |
not set |
any |
||
manmanual |
Manual name displayed in the manpage footer. |
not set |
any |
||
Secure attributes (can only be set from the commandline 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 |
|
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 |
|
skip-front-matter |
If set, consume YAML-style front matter at the top of the document and store it in the |
not set |
empty |
CLI or API |
[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.
[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.
A.3. Predefined Attributes for Character Replacements
Attribute name | Replacement text | Appearance |
---|---|---|
blank |
_nothing_ |
|
empty |
_nothing_ |
|
sp |
_single space_ |
|
nbsp |
  |
|
zwsp^[4]^ |
​ |
|
wj^[5]^ |
⁠ |
|
apos |
' |
' |
quot |
" |
" |
lsquo |
‘ |
‘ |
rsquo |
’ |
’ |
ldquo |
“ |
“ |
rdquo |
” |
” |
deg |
° |
° |
plus |
+ |
+ |
brvbar |
¦ |
¦ |
vbar |
| |
| |
amp |
& |
& |
lt |
< |
< |
gt |
> |
> |
startsb |
[ |
[ |
endsb |
] |
] |
caret |
^ |
^ |
asterisk |
* |
* |
tilde |
~ |
~ |
backslash |
\ |
\ |
backtick |
` |
` |
two-colons |
:: |
:: |
two-semicolons |
;; |
;; |
cpp |
C++ |
C++ |
[1] Some replacements are Unicode characters, whereas others are numeric character references. The character references (e.g., ") are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer (i.e., the browser). It’s up to the converter to transform the reference into something the renderer understands (something both the manpage and PDF converter handle).
[2] Asciidoctor does not prevent you from reassigning predefined attributes. However, it’s best to treat them as read-only unless the output format requires the use of a different encoding scheme. These attributes are an effective tool for decoupling content and presentation.
[3] Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., € resolves to €). However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined. Our recommendation is avoid using named character references—with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). Instead, use numeric character references (e.g., €).
[4] The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.
[5] The word joiner (WJ) is a code point in Unicode prevents a line break at its position.