Asciidoctor User Manual

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.

Environment attributes
Attribute	Description	Example Value
`asciidoctor`	Set if the current processor is Asciidoctor.
`asciidoctor-version`	Asciidoctor version.	`1.5.6.1`
`backend`	Backend used to create the output file.	`html5`
`basebackend`	The backend value minus any trailing numbers. For example, if the backend is `docbook5`, the basebackend is `docbook`.	`html`
`docdate`	Last modified date of the source document.^[1,2]	`2015-01-04`
`docdatetime`	Last modified date and time of the source document.^[1,2]	`2015-01-04 19:26:06 GMT+0000`
`docdir`	Full path of the directory that contains the source document.	`/home/user/docs`
`docfile`	Full path of the source document.	`/home/user/docs/userguide.adoc`
`docfilesuffix`	File extension of the source document, including the leading period. Introduced in 1.5.6.	`.adoc`
`docname`	Root name of the source document (no leading path or file extension).	`userguide`
`doctime`	Last modified time of the source document.^[1,2]	`19:26:06 GMT+0000`
`doctype`	Document type (article, book or manpage).	`article`
`docyear`	Year that the document was last modified.^[1,2]	`2015`
`embedded`	Set if content is being converted to an embeddable document (body only).
`filetype`	File extension of the output file name (without leading period).	`html`
`htmlsyntax`	Syntax used when generating the HTML output (html or xhtml).	`html`
`localdate`	Date when the document was converted.^[2]	`2016-02-17`
`localdatetime`	Date and time when the document was converted.^[2]	`2016-02-17 19:31:05 GMT+0000`
`localtime`	Time when the document was converted.^[2]	`19:31:05 GMT+0000`
`localyear`	Year when the document was converted.^[2]	`2016`
`outdir`	Full path of the output directory.	`/home/user/docs/dist`
`outfile`	Full path of the output file.	`/home/user/docs/dist/userguide.html`
`outfilesuffix`	File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc). (The value is not updated to match the file extension of the output file when one is specified explicitly). Safe to modify.	`.html`
`safe-mode-level`	Numeric value of the safe mode setting. (UNSAFE=0, SAFE=10, SERVER=10, SECURE=20).	`20`
`safe-mode-name`	Textual value of the safe mode setting.	`SERVER`
`safe-mode-unsafe`	Set if the safe mode is UNSAFE.
`safe-mode-safe`	Set if the safe mode is SAFE.
`safe-mode-server`	Set if the safe mode is SERVER.
`safe-mode-secure`	Set if the safe mode is SECURE.
`user-home`	Home directory of the current user. Resolves to `.` if the safe mode is SERVER or greater.	`/home/user`

^[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 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 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.

Built-in document attributes
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		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		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
Internationalization and numbering
appendix-caption	Sets the text used to prefix appendix titles.	Appendix	any		Appendix, Translating built-in labels
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		Admonition, Translating built-in labels
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		Translating built-in labels
example-number	Stores the number for the current numbered example.^[2]	5	integer
figure-caption	Sets the text used to label figures.	Figure	any		Images, Translating built-in labels
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		Admonition, Translating built-in labels
lang	Set the value of the `lang` attribute on the root element of the output document.	en	Valid XML country code		Translating built-in 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		Footer docinfo files, Translating built-in labels
listing-caption	Sets the text used to label listing blocks.	not set	any		Translating built-in labels
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		Translating built-in labels
nolang	Prevents the `lang` attribute from being added to root element of the output document.	not set	empty
note-caption	Sets the text used to label NOTE admonitions when icons are not enabled.	Note	any		Admonition, Translating built-in labels
preface-title	Sets the title text for an anonymous preface when the doctype is book.	not set	any		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, 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-caption` attribute to the document header with an empty value.	Table	any		Translating built-in labels
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		Admonition, Translating built-in labels
toc-title	Title for the table of contents.	Table of Contents	any		Table of Contents, Translating built-in labels
untitled-label	Used as the default document title if the document does not have a document title.	Untitled	any		Translating built-in labels
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		Translating built-in labels
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
author	Sets the document’s main author. Can be set automatically via the author info line.	not set	any		Header
authorinitials	Sets the author’s initials (e.g., JD). Derived automatically from the author attribute by default.	not set	any		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		Metadata
copyright	If set, adds a `copyright` meta element inside the HTML document head.	not set	any		Metadata
doctitle	Sets the document title. Set automatically to section title if document begins with level-0 section.	Based on content.	any		Document Title
description	If set, adds a `description` meta element inside the HTML document head.	not set	any		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		Header
firstname	Sets the author’s first name. Can be set automatically via the author info line.	not set	any		Header
front-matter	If `skip-front-matter` is set, holds any YAML-style front matter skimmed from the top of the document.	Front matter content, if captured.	any		Front Matter Added for Static Site Generators
keywords	If set, adds a `keywords` meta element inside the HTML document head.	not set	any		Metadata
lastname	Sets the author’s last name. Can be set automatically via the author info line.	not set	any		Header
middlename	Sets the author’s middle name or initial. Can be set automatically via the author info line.	not set	any		Header
orgname	If set, add an `<orgname>` element with this value to the DocBook info element.	not set	any		Metadata
revdate	Sets the revision date. Can be set automatically via the revision info line.	not set	any		Header
revremark	Sets the revision description. Can be set automatically via the revision info line.	not set	any		Header
revnumber	Sets the revision number. Can be set automatically via the revision info line.	not set	any		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		Document Title
Section titles and table of contents
idprefix	Sets prefix used for auto-generated section IDs.	_	Valid XML ID start character.		Auto-generated IDs
idseparator	Sets word separator used in auto-generated section IDs.	_	Valid XML ID character.		Auto-generated IDs
leveloffset	Pushes the level of subsequent headings down, to make file inclusion more useful.	0	(+/-)0–5. (A leading + or - makes it relative).		Partitioning large documents and using leveloffset
sectanchors	If set, adds an anchor in front of the section title when the mouse cursor hovers over it.	not set (No anchors).	empty		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		Auto-generated IDs
sectlinks	Turns section titles into self-referencing links.	not set	empty		Links
sectnums	If set, numbers sections to depth specified by sectnumlevels.	not set (Sections are not numbered).	empty		Numbering
sectnumlevels	controls the depth of section numbering	3	0–5		Numbering depth
title-separator	The character used to separate the main title and subtitle in the document title.	:	any		Subtitle Partitioning
toc	Switches the table of contents on, and defines its location.	not set	auto, left, right, macro or preamble		Table of Contents
toclevels	Maximum section level to display.	2	1–5		Table of Contents
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		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		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		Naming docinfo files
docinfodir	The location where docinfo files are resolved.	The base directory.	Directory		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.		Attribute substitution in docinfo files
doctype	Set the output document type.	article	article, book, inline or manpage		Document Types
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		Equations and Formulas, 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		URLs
linkattrs	Parse attributes inside the link macro.	not set (Do not parse).	empty		URLs
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		Footer docinfo files
nofootnotes	Turn off display of footnotes.	not set	empty		Footnotes
noheader	Suppresses output of the header.	not set	empty		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
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
showtitle	If set, displays an embedded document’s title. Mutually exclusive with the `notitle` attribute.	not set	empty		Document Title
stem	Enables mathematics processing or sets the processor used.	not set	empty (defaults to asciimath), asciimath or latexmath		Inline Stem Content
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		Applying a Theme and 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.		DocBook
xrefstyle	The formatting style to apply to cross reference text. Introduced in 1.5.6.	not set	full, short, or basic		Customizing the Cross Reference Text
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		Icons
iconfont-name	Overrides the name of the icon font stylesheet. Only used when `icons` attribute is set to `font`.	font-awesome	any		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		Icons
icons	Chooses icons instead of text for admonitions.	not set (image)	font or image		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		Icons
icontype	File type for image icons. Only used when `icons` attribute is set to `image`.	png	any, but typically jpg, tiff etc.		Icons
imagesdir	Where image files are resolved.	not set (Same directory as document).	Directory		Images
Code highlighting and formatting
coderay-css	Controls whether CodeRay uses CSS classes or inline styles.	class	class or style		CodeRay
coderay-linenums-mode	Sets how Coderay inserts line numbers into source listings.	table	table or inline		CodeRay
coderay-unavailable	If set, tells the processor not to attempt to load CodeRay.	not set	empty		CodeRay
highlightjsdir	Location of the highlight.js source code highlighter library.	not set	Directory		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.		highlight.js
prettifydir	Location of the prettify source code highlighter library.	not set (Uses CDN).	Directory		Syntax Highlighting Source Code
prettify-theme	Sets the name of the theme used by the prettify source code highlighter.	prettify	A style name recognized by prettify.		Syntax Highlighting Source Code
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		Pygments
pygments-linenums-mode	Sets how Pygments inserts line numbers into source listings.	table	table or inline		Pygments
pygments-style	Sets the name of the style used by the Pygments source code highlighter	default	A style name recognized by Pygments.		Pygments
pygments-unavailable	If set, tells the processor not to attempt to load Pygments.	not set	empty		Pygments
source-highlighter	Source code highlighter to use.	not set	coderay, highlightjs, prettify or pygments		Syntax Highlighting Source Code
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.		Syntax Highlighting Source Code
source-linenums-option	Turns on line numbers option by default for source code listings. Introduced in 1.5.6.	not set	empty		Syntax Highlighting Source Code
HTML styling
copycss	If set, copy the CSS files to the output.	empty (File is copied if `linkcss` is set).	empty		Applying a Theme
css-signature	If set, assign the value to the `id` attribute of the `<body>` element (HTML only). The prefered approach is to assign an ID to the document title.	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) set (when safe mode is SECURE)	empty		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)
stylesdir	Location for resolving CSS stylesheets.	. (Same directory as document).	Directory		Creating a Theme
stylesheet	Name of a CSS stylesheet to replace the default one.	not set (The default stylesheet is used).	File name		Applying a Theme
toc-class	The CSS class on the table of contents container.	toc	Valid CSS class name		Table of Contents
Manpage attributes (relevant only when using the manpage doctype and/or converter)
mantitle	Metadata for manpage output.	Based on content.	any		Man Pages
manvolnum	Metadata for manpage output.	Based on content.	any		Man Pages
manname	Metadata for manpage output.	Based on content.	any		Man Pages
manpurpose	Metadata for manpage output.	Based on content.	any		Man Pages
man-linkstyle	Style the links in the manpage output.	blue R <>	Link format sequence		Man Pages
mansource	The source (e.g., application and version) to which the manpage pertains.	not set	any		Man Pages
manmanual	Manual name displayed in the manpage footer.	not set	any		Man Pages
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	Include Content from a 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 front matter 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.

^[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

Predefined attributes for character replacements ^[1][2][3]
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.