Document Attributes Reference

Document attributes are used either to configure behavior in the processor or to relay information about the document and its environment. This page catalogs all the built-in (i.e., reserved) document attributes in AsciiDoc.

Unless otherwise marked, these attributes can be modified (set or unset) from the API using the :attributes option, from the CLI using the -a option, or in the document (often in the document header) using an attribute entry.

Use the follow legend to understand the columns and values in the tables on this page.

Set By Default	The attribute is automatically set and assigned a default value by the AsciiDoc processor. The default value is indicated in bold (e.g., `skip`).
Allowable Values	Allowable values for the attribute. Numeric values and values shown in italic are instructional and indicate a value type (e.g., any, empty, number, 1–5, etc.). any — Any value is accepted. empty — Indicates the attribute doesn’t require an explicit value. The attribute is simply turned on by being set. empty[=`effective`] — In some cases, an empty value is interpreted by the processor as one of the allowable non-empty values. This effective value is prefixed with an equals sign and enclosed in square brackets (e.g., [=`auto`]). An attribute reference will resolve to an empty value rather than the effective value. (`implied`) — Built-in attributes that are not set may have an implied value. The implied value is enclosed in parentheses (e.g., (`attributes`)). An implied value can’t be resolved using an attribute reference. If the attribute doesn’t accept any or empty, than you must only assign one of the allowable values or specified value type.
Header Only	The attribute must be set or unset by the end of the document header (i.e., set by the API, CLI, or in the document header). Otherwise, the assignment won’t have any effect on the document. If an attribute is not marked as Header Only, it can be set anywhere in the document, assuming the attribute is not locked by the API or CLI. However, changing an attribute only affects behavior for content that follows the assignment (in document order).

Intrinsic attributes

Intrinsic attributes are set automatically by the processor. These attributes provide information about the document being processed (e.g., docfile), the security mode under which the processor is running (e.g., safe-mode-name), and information about the user’s environment (e.g., user-home).

Many of these attributes are read only, which means they can’t be modified (with some exceptions). Attributes which are not are marked as modifiable. Attributes marked as both modifiable and API/CLI Only can only be set from the API or CLI. All other attributes marked as modifiable must be set by the end of the header (i.e., Header Only).

Name Allowable Values Modifiable API/CLI Only Notes

Name	Allowable Values	Modifiable	API/CLI Only	Notes
`backend`	any ex. html5	Yes	No	The backend used to select and activate the converter that creates the output file. Usually named according to the output format (e.g., `html5`)
`backend-<backend>`	empty	No	n/a	A convenience attribute for checking which backend is selected. <backend> is the value of the `backend` attribute (e.g., `backend-html5`). Only one such attribute is set at time.
`basebackend`	any ex. html	No	n/a	The generic backend on which the backend is based. Typically derived from the backend value minus trailing numbers (e.g., the basebackend for `docbook5` is `docbook`). May also indicate the internal backend employed by the converter (e.g., the basebackend for `pdf` is `html`).
`basebackend-<basebackend>`	empty	No	n/a	A convenience attribute for checking which basebackend is active. <basebackend> is the value of the `basebackend` attribute (e.g., `basebackend-html`). Only one such attribute is set at time.
`docdate`	date (ISO) ex. 2019-01-04	Yes	No	Last modified date of the source document.^[1,2]
`docdatetime`	datetime (ISO) ex. 2019-01-04 19:26:06 UTC	Yes	No	Last modified date and time of the source document.^[1,2]
`docdir`	directory path ex. /home/user/docs	If input is a string	Yes	Full path of the directory that contains the source document. Empty if the safe mode is SERVER or SECURE (to conceal the file’s location).
`docfile`	file path ex. /home/user/docs/userguide.adoc	If input is a string	Yes	Full path of the source document. Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file’s location).
`docfilesuffix`	file extension ex. .adoc	If input is a string	Yes	File extension of the source document, including the leading period.
`docname`	file stem basename ex. userguide	If input is a string	Yes	Root name of the source document (no leading path or file extension).
`doctime`	time (ISO) ex. 19:26:06 UTC	Yes	No	Last modified time of the source document.^[1,2]
`doctype-<doctype>`	empty	No	n/a	A convenience attribute for checking the doctype of the document. <doctype> is the value of the `doctype` attribute (e.g., `doctype-book`). Only one such attribute is set at time.
`docyear`	integer ex. 2023	Yes	No	Year that the document was last modified.^[1,2]
`embedded`	empty	No	n/a	Only set if content is being converted to an embedded document (i.e., body of document only).
`filetype`	any ex. html	If input is a string	Yes	File extension of the output file name (without leading period).
`filetype-<filetype>`	empty	No	n/a	A convenience attribute for checking the filetype of the output. <filetype> is the value of the `filetype` attribute (e.g., `filetype-html`). Only one such attribute is set at time.
`htmlsyntax`	`html` `xml`	No	n/a	Syntax used when generating the HTML output. Controlled by and derived from the backend name (html=html or xhtml=html).
`localdate`	date (ISO) ex. 2019-02-17	Yes	No	Date when the document was converted.^[2]
`localdatetime`	datetime (ISO) ex. 2019-02-17 19:31:05 UTC	Yes	No	Date and time when the document was converted.^[2]
`localtime`	time (ISO) ex. 19:31:05 UTC	Yes	No	Time when the document was converted.^[2]
`localyear`	integer ex. 2023	Yes	No	Year when the document was converted.^[2]
`outdir`	directory path ex. /home/user/docs/dist	No	n/a	Full path of the output directory. (Cannot be referenced in the content. Only available to the API once the document is converted).
`outfile`	file path ex. /home/user/docs/dist/userguide.html	No	n/a	Full path of the output file. (Cannot be referenced in the content. Only available to the API once the document is converted).
`outfilesuffix`	file extension ex. .html	Yes	No	File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.).
`safe-mode-level`	`0` `1` `10` `20`	No	n/a	Numeric value of the safe mode setting. (0=UNSAFE, 1=SAFE, 10=SERVER, 20=SECURE).
`safe-mode-name`	`UNSAFE` `SAFE` `SERVER` `SECURE`	No	n/a	Textual value of the safe mode setting.
`safe-mode-unsafe`	empty	No	n/a	Set if the safe mode is UNSAFE.
`safe-mode-safe`	empty	No	n/a	Set if the safe mode is SAFE.
`safe-mode-server`	empty	No	n/a	Set if the safe mode is SERVER.
`safe-mode-secure`	empty	No	n/a	Set if the safe mode is SECURE.
`user-home`	directory path ex. /home/user	No	n/a	Full path of the home directory for the current user. Masked as `.` if the safe mode is SERVER or SECURE.

backend

any
ex. html5

Yes

The backend used to select and activate the converter that creates the output file. Usually named according to the output format (e.g., html5)

backend-<backend>

empty

n/a

A convenience attribute for checking which backend is selected. <backend> is the value of the backend attribute (e.g., backend-html5). Only one such attribute is set at time.

basebackend

any
ex. html

n/a

The generic backend on which the backend is based. Typically derived from the backend value minus trailing numbers (e.g., the basebackend for docbook5 is docbook). May also indicate the internal backend employed by the converter (e.g., the basebackend for pdf is html).

basebackend-<basebackend>

empty

n/a

A convenience attribute for checking which basebackend is active. <basebackend> is the value of the basebackend attribute (e.g., basebackend-html). Only one such attribute is set at time.

docdate

date (ISO)
ex. 2019-01-04

Yes

Last modified date of the source document.^[1,2]

docdatetime

datetime (ISO)
ex. 2019-01-04 19:26:06 UTC

Yes

Last modified date and time of the source document.^[1,2]

docdir

directory path
ex. /home/user/docs

If input is a string

Yes

Full path of the directory that contains the source document. Empty if the safe mode is SERVER or SECURE (to conceal the file’s location).

docfile

file path
ex. /home/user/docs/userguide.adoc

If input is a string

Yes

Full path of the source document. Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file’s location).

docfilesuffix

file extension
ex. .adoc

If input is a string

Yes

File extension of the source document, including the leading period.

docname

file stem basename
ex. userguide

If input is a string

Yes

Root name of the source document (no leading path or file extension).

doctime

time (ISO)
ex. 19:26:06 UTC

Yes

Last modified time of the source document.^[1,2]

doctype-<doctype>

empty

n/a

A convenience attribute for checking the doctype of the document. <doctype> is the value of the doctype attribute (e.g., doctype-book). Only one such attribute is set at time.

docyear

integer
ex. 2023

Yes

Year that the document was last modified.^[1,2]

embedded

empty

n/a

Only set if content is being converted to an embedded document (i.e., body of document only).

filetype

any
ex. html

If input is a string

Yes

File extension of the output file name (without leading period).

filetype-<filetype>

empty

n/a

A convenience attribute for checking the filetype of the output. <filetype> is the value of the filetype attribute (e.g., filetype-html). Only one such attribute is set at time.

htmlsyntax

html
xml

n/a

Syntax used when generating the HTML output. Controlled by and derived from the backend name (html=html or xhtml=html).

localdate

date (ISO)
ex. 2019-02-17

Yes

Date when the document was converted.^[2]

localdatetime

datetime (ISO)
ex. 2019-02-17 19:31:05 UTC

Yes

Date and time when the document was converted.^[2]

localtime

time (ISO)
ex. 19:31:05 UTC

Yes

Time when the document was converted.^[2]

localyear

integer
ex. 2023

Yes

Year when the document was converted.^[2]

outdir

directory path
ex. /home/user/docs/dist

n/a

Full path of the output directory. (Cannot be referenced in the content. Only available to the API once the document is converted).

outfile

file path
ex. /home/user/docs/dist/userguide.html

n/a

Full path of the output file. (Cannot be referenced in the content. Only available to the API once the document is converted).

outfilesuffix

file extension
ex. .html

Yes

File extension of the output file (starting with a period) as determined by the backend (.html for html, .xml for docbook, etc.).

safe-mode-level

0
1
10
20

n/a

Numeric value of the safe mode setting. (0=UNSAFE, 1=SAFE, 10=SERVER, 20=SECURE).

safe-mode-name

UNSAFE
SAFE
SERVER
SECURE

n/a

Textual value of the safe mode setting.

safe-mode-unsafe

empty

n/a

Set if the safe mode is UNSAFE.

safe-mode-safe

empty

n/a

Set if the safe mode is SAFE.

safe-mode-server

empty

n/a

Set if the safe mode is SERVER.

safe-mode-secure

empty

n/a

Set if the safe mode is SECURE.

user-home

directory path
ex. /home/user

n/a

Full path of the home directory for the current user. Masked as . if the safe mode is SERVER or SECURE.

^[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 the source date epoch specification for more information about the SOURCE_DATE_EPOCH environment variable. Otherwise, the date is expressed in the local time zone, which is reported as a time zone offset (e.g., -0600) or UTC if the time zone offset is 0). To force the use of UTC, set the TZ=UTC environment variable when invoking Asciidoctor.

Compliance attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`attribute-missing`	`drop` `drop-line` `skip` `warn`	Yes	No	Controls how missing attribute references are handled.
`attribute-undefined`	`drop` `drop-line`	Yes	No	Controls how attribute unassignments are handled.
`compat-mode`	empty	No	No	Controls when the legacy parsing mode is used to parse the document.
`experimental`	empty	No	Yes	Enables Button and Menu UI Macros and the Keyboard Macro.
`reproducible`	empty	No	Yes	Prevents last-updated date from being added to HTML footer or DocBook info element. Useful for storing the output in a source code control system as it prevents spurious changes every time you convert the document. Alternately, you can use the SOURCE_DATE_EPOCH environment variable, which sets the epoch of all source documents and the local datetime to a fixed value.
`skip-front-matter`	empty	No	Yes	Consume YAML-style frontmatter at top of document and store it in `front-matter` attribute.

attribute-missing

drop
drop-line
skip
warn

Yes

Controls how missing attribute references are handled.

attribute-undefined

drop
drop-line

Yes

Controls how attribute unassignments are handled.

compat-mode

empty

Controls when the legacy parsing mode is used to parse the document.

experimental

empty

Yes

Enables Button and Menu UI Macros and the Keyboard Macro.

reproducible

empty

Yes

Prevents last-updated date from being added to HTML footer or DocBook info element. Useful for storing the output in a source code control system as it prevents spurious changes every time you convert the document. Alternately, you can use the SOURCE_DATE_EPOCH environment variable, which sets the epoch of all source documents and the local datetime to a fixed value.

skip-front-matter

empty

Yes

Consume YAML-style frontmatter at top of document and store it in front-matter attribute.

Localization and numbering attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`appendix-caption`	any `Appendix`	Yes	No	Label added before an appendix title.
`appendix-number`	character (`@`)	No	No	Sets the seed value for the appendix number sequence.^[1]
`appendix-refsig`	any `Appendix`	Yes	No	Signifier added to Appendix title cross references.
`caution-caption`	any `Caution`	Yes	No	Text used to label CAUTION admonitions when icons aren’t enabled.
`chapter-number`	number (`0`)	No	No	Sets the seed value for the chapter number sequence.^[1] Book doctype only.
`chapter-refsig`	any `Chapter`	Yes	No	Signifier added to Chapter titles in cross references. Book doctype only.
`chapter-signifier`	any	No	No	Label added to level 1 section titles (chapters). Book doctype only.
`example-caption`	any `Example`	Yes	No	Text used to label example blocks.
`example-number`	number (`0`)	No	No	Sets the seed value for the example number sequence.^[1]
`figure-caption`	any `Figure`	Yes	No	Text used to label images and figures.
`figure-number`	number (`0`)	No	No	Sets the seed value for the figure number sequence.^[1]
`footnote-number`	number (`0`)	No	No	Sets the seed value for the footnote number sequence.^[1]
`important-caption`	any `Important`	Yes	No	Text used to label IMPORTANT admonitions when icons are not enabled.
`lang`	BCP 47 language tag (`en`)	No	Yes	Language tag specified on document element of the output document. Refer to the lang and xml:lang attributes section of the HTML specification to learn about the acceptable values for this attribute.
`last-update-label`	any `Last updated`	Yes	Yes	Text used for “Last updated” label in footer.
`listing-caption`	any	No	No	Text used to label listing blocks.
`listing-number`	number (`0`)	No	No	Sets the seed value for the listing number sequence.^[1]
`manname-title`	any (`Name`)	No	Yes	Label for program name section in the man page.
`nolang`	empty	No	Yes	Prevents `lang` attribute from being added to root element of the output document.
`note-caption`	any `Note`	Yes	No	Text used to label NOTE admonitions when icons aren’t enabled.
`part-refsig`	any `Part`	Yes	No	Signifier added to Part titles in cross references. Book doctype only.
`part-signifier`	any	No	No	Label added to level 0 section titles (parts). Book doctype only.
`preface-title`	any	No	No	Title text for an anonymous preface when `doctype` is `book`.
`section-refsig`	any `Section`	Yes	No	Signifier added to title of numbered sections in cross reference text.
`table-caption`	any `Table`	Yes	No	Text of label prefixed to table titles.
`table-number`	number (`0`)	No	No	Sets the seed value for the table number sequence.^[1]
`tip-caption`	any `Tip`	Yes	No	Text used to label TIP admonitions when icons aren’t enabled.
`toc-title`	any `Table of Contents`	Yes	Yes	Title for table of contents.
`untitled-label`	any `Untitled`	Yes	Yes	Default document title if document doesn’t have a document title.
`version-label`	any `Version`	Yes	Yes	See Version Label Attribute.
`warning-caption`	any `Warning`	Yes	No	Text used to label WARNING admonitions when icons aren’t enabled.

appendix-caption

any
Appendix

Yes

Label added before an appendix title.

appendix-number

character
(@)

Sets the seed value for the appendix number sequence.^[1]

appendix-refsig

any
Appendix

Yes

Signifier added to Appendix title cross references.

caution-caption

any
Caution

Yes

Text used to label CAUTION admonitions when icons aren’t enabled.

chapter-number

number
(0)

Sets the seed value for the chapter number sequence.^[1] Book doctype only.

chapter-refsig

any
Chapter

Yes

Signifier added to Chapter titles in cross references. Book doctype only.

chapter-signifier

any

Label added to level 1 section titles (chapters). Book doctype only.

example-caption

any
Example

Yes

Text used to label example blocks.

example-number

number
(0)

Sets the seed value for the example number sequence.^[1]

figure-caption

any
Figure

Yes

Text used to label images and figures.

figure-number

number
(0)

Sets the seed value for the figure number sequence.^[1]

footnote-number

number
(0)

Sets the seed value for the footnote number sequence.^[1]

important-caption

any
Important

Yes

Text used to label IMPORTANT admonitions when icons are not enabled.

lang

BCP 47 language tag
(en)

Yes

Language tag specified on document element of the output document. Refer to the lang and xml:lang attributes section of the HTML specification to learn about the acceptable values for this attribute.

last-update-label

any
Last updated

Yes

Text used for “Last updated” label in footer.

listing-caption

any

Text used to label listing blocks.

listing-number

number
(0)

Sets the seed value for the listing number sequence.^[1]

manname-title

any
(Name)

Yes

Label for program name section in the man page.

nolang

empty

Yes

Prevents lang attribute from being added to root element of the output document.

note-caption

any
Note

Yes

Text used to label NOTE admonitions when icons aren’t enabled.

part-refsig

any
Part

Yes

Signifier added to Part titles in cross references. Book doctype only.

part-signifier

any

Label added to level 0 section titles (parts). Book doctype only.

preface-title

any

Title text for an anonymous preface when doctype is book.

section-refsig

any
Section

Yes

Signifier added to title of numbered sections in cross reference text.

table-caption

any
Table

Yes

Text of label prefixed to table titles.

table-number

number
(0)

Sets the seed value for the table number sequence.^[1]

tip-caption

any
Tip

Yes

Text used to label TIP admonitions when icons aren’t enabled.

toc-title

any
Table of Contents

Yes

Title for table of contents.

untitled-label

any
Untitled

Yes

Default document title if document doesn’t have a document title.

version-label

any
Version

Yes

See Version Label Attribute.

warning-caption

any
Warning

Yes

Text used to label WARNING admonitions when icons aren’t enabled.

Document metadata attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`app-name`	any	No	Yes	Adds `application-name` meta element for mobile devices inside HTML document head.
`author`	any	Extracted from author info line	Yes	Can be set automatically via the author info line or explicitly. See Author Information.
`authorinitials`	any	Extracted from `author` attribute	Yes	Derived from the author attribute by default. See Author Information.
`authors`	any	Extracted from author info line	Yes	Can be set automatically via the author info line or explicitly as a comma-separated value list. See Author Information.
`copyright`	any	No	Yes	Adds `copyright` meta element in HTML document head.
`doctitle`	any	Yes, if document has a doctitle	Yes	See doctitle attribute.
`description`	any	No	Yes	Adds description meta element in HTML document head.
`email`	any	Extracted from author info line	Yes	Can be any inline macro, such as a URL. See Author Information.
`firstname`	any	Extracted from author info line	Yes	See Author Information.
`front-matter`	any	Yes, if front matter is captured	n/a	If `skip-front-matter` is set via the API or CLI, any YAML-style frontmatter skimmed from the top of the document is stored in this attribute.
`keywords`	any	No	Yes	Adds keywords meta element in HTML document head.
`lastname`	any	Extracted from author info line	Yes	See Author Information.
`middlename`	any	Extracted from author info line	Yes	See Author Information.
`orgname`	any	No	Yes	Adds `<orgname>` element value to DocBook info element.
`revdate`	any	Extracted from revision info line	Yes	See Revision Information.
`revremark`	any	Extracted from revision info line	Yes	See Revision Information.
`revnumber`	any	Extracted from revision info line	Yes	See Revision Information.
`title`	any	No	Yes	Value of `<title>` element in HTML `<head>` or main DocBook `<info>` of output document. Used as a fallback when the document title is not specified. See title attribute.

app-name

any

Yes

Adds application-name meta element for mobile devices inside HTML document head.

author

any

Extracted from author info line

Yes

Can be set automatically via the author info line or explicitly. See Author Information.

authorinitials

any

Extracted from author attribute

Yes

Derived from the author attribute by default. See Author Information.

authors

any

Extracted from author info line

Yes

Can be set automatically via the author info line or explicitly as a comma-separated value list. See Author Information.

copyright

any

Yes

Adds copyright meta element in HTML document head.

doctitle

any

Yes, if document has a doctitle

Yes

See doctitle attribute.

description

any

Yes

Adds description meta element in HTML document head.

email

any

Extracted from author info line

Yes

Can be any inline macro, such as a URL. See Author Information.

firstname

any

Extracted from author info line

Yes

See Author Information.

front-matter

any

Yes, if front matter is captured

n/a

If skip-front-matter is set via the API or CLI, any YAML-style frontmatter skimmed from the top of the document is stored in this attribute.

keywords

any

Yes

Adds keywords meta element in HTML document head.

lastname

any

Extracted from author info line

Yes

See Author Information.

middlename

any

Extracted from author info line

Yes

See Author Information.

orgname

any

Yes

Adds <orgname> element value to DocBook info element.

revdate

any

Extracted from revision info line

Yes

See Revision Information.

revremark

any

Extracted from revision info line

Yes

See Revision Information.

revnumber

any

Extracted from revision info line

Yes

See Revision Information.

title

any

Yes

Value of <title> element in HTML <head> or main DocBook <info> of output document. Used as a fallback when the document title is not specified. See title attribute.

Section title and table of contents attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`idprefix`	valid XML ID start character `_`	Yes	No	Prefix of auto-generated section IDs. See Change the ID prefix.
`idseparator`	valid XML ID character `_`	Yes	No	Word separator used in auto-generated section IDs. See Change the ID word separator.
`leveloffset`	[+-]0–5	No	No	Increases or decreases level of headings below assignment. A leading + or - makes the value relative.
`partnums`	empty	No	No	Enables numbering of parts. See Number book parts. Book doctype only.
`sectanchors`	empty	No	No	Adds anchor in front of section title on mouse cursor hover.
`sectids`	*empty*	Yes	No	Generates and assigns an ID to any section that does not have an ID. See Disable automatic ID generation.
`sectlinks`	empty	No	No	Turns section titles into self-referencing links.
`sectnums`	empty `all`	No	No	Numbers sections to depth specified by `sectnumlevels`.
`sectnumlevels`	0–5 (`3`)	No	No	Controls depth of section numbering.
`title-separator`	any	No	Yes	Character used to separate document title and subtitle.
`toc`	empty[=`auto`] `auto` `left` `right` `macro` `preamble`	No	Yes	Turns on table of contents and specifies its location.
`toclevels`	1–5 (`2`)	No	Yes	Maximum section level to display.
`fragment`	empty	No	Yes	Informs parser that document is a fragment and that it shouldn’t enforce proper section nesting.

idprefix

valid XML ID start character
_

Yes

Prefix of auto-generated section IDs. See Change the ID prefix.

idseparator

valid XML ID character
_

Yes

Word separator used in auto-generated section IDs. See Change the ID word separator.

leveloffset

[+-]0–5

Increases or decreases level of headings below assignment. A leading + or - makes the value relative.

partnums

empty

Enables numbering of parts. See Number book parts. Book doctype only.

sectanchors

empty

Adds anchor in front of section title on mouse cursor hover.

sectids

empty

Yes

Generates and assigns an ID to any section that does not have an ID. See Disable automatic ID generation.

sectlinks

empty

Turns section titles into self-referencing links.

sectnums

empty
all

Numbers sections to depth specified by sectnumlevels.

sectnumlevels

0–5
(3)

Controls depth of section numbering.

title-separator

any

Yes

Character used to separate document title and subtitle.

toc

empty[=auto]
auto
left
right
macro
preamble

Yes

Turns on table of contents and specifies its location.

toclevels

1–5
(2)

Yes

Maximum section level to display.

fragment

empty

Yes

Informs parser that document is a fragment and that it shouldn’t enforce proper section nesting.

General content and formatting attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`asset-uri-scheme`	empty `http` (`https`)	No	Yes	Controls protocol used for assets hosted on a CDN.
`cache-uri`	empty	No	Yes	Cache content read from URIs.
`data-uri`	empty	No	Yes	Embed graphics as data-uri elements in HTML elements so file is completely self-contained.
`docinfo`	empty[=`private`] `shared` `private` `shared-head` `private-head` `shared-footer` `private-footer`	No	Yes	Read input from one or more DocBook info files.
`docinfodir`	directory path	No	Yes	Location of docinfo files. Defaults to directory of source file if not specified.
`docinfosubs`	comma-separated substitution names (`attributes`)	No	Yes	AsciiDoc substitutions that are applied to docinfo content.
`doctype`	`article` `book` `inline` `manpage`	Yes	Yes	Output document type.
`eqnums`	empty[=`AMS`] `AMS` `all` `none`	No	Yes	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. See equation numbering in MathJax.
`hardbreaks-option`	empty	No	No	Preserve hard line breaks.
`hide-uri-scheme`	empty	No	No	Hides URI scheme for raw links.
`media`	`prepress` `print` (`screen`)	No	Yes	Specifies media type of output and enables behavior specific to that media type. PDF converter only.
`nofooter`	empty	No	Yes	Turns off footer.
`nofootnotes`	empty	No	Yes	Turns off footnotes.
`noheader`	empty	No	Yes	Turns off header.
`notitle`	empty	No	Yes	Hides the doctitle in an embedded document. Mutually exclusive with the `showtitle` attribute.
`outfilesuffix`	*file extension* ex. .html	Yes	Yes	File extension of output file, including dot (`.`), such as `.html`.
`pagewidth`	integer (`425`)	No	Yes	Page width used to calculate the absolute width of tables in the DocBook output.
`relfileprefix`	empty path segment	No	No	The path prefix to add to relative xrefs.
`relfilesuffix`	*file extension* path segment ex. .html	Yes	No	The path suffix (e.g., file extension) to add to relative xrefs. Defaults to the value of the `outfilesuffix` attribute. (Preferred over modifying outfilesuffix).
`show-link-uri`	empty	No	No	Prints the URI of a link after the link text. PDF converter only.
`showtitle`	empty	No	Yes	Displays the doctitle in an embedded document. Mutually exclusive with the `notitle` attribute.
`stem`	`empty`[=`asciimath`] `asciimath` `latexmath`	No	Yes	Enables mathematics processing and interpreter.
`table-frame`	(`all`) `ends` `sides` `none`	No	No	Controls default value for `frame` attribute on tables.
`table-grid`	(`all`) `cols` `rows` `none`	No	No	Controls default value for `grid` attribute on tables.
`table-stripes`	(`none`) `even` `odd` `hover` `all`	No	No	Controls default value for `stripes` attribute on tables.
`tabsize`	integer (≥ 0)	No	No	Converts tabs to spaces in verbatim content blocks (e.g., listing, literal).
`webfonts`	*empty*	Yes	Yes	Control whether webfonts are loaded when using the default stylesheet. When set to empty, uses the default font collection from Google Fonts. A non-empty value replaces the `family` query string parameter in the Google Fonts URL.
`xrefstyle`	`full` `short` `basic`	No	No	Formatting style to apply to cross reference text.

asset-uri-scheme

empty
http
(https)

Yes

Controls protocol used for assets hosted on a CDN.

cache-uri

empty

Yes

Cache content read from URIs.

data-uri

empty

Yes

Embed graphics as data-uri elements in HTML elements so file is completely self-contained.

docinfo

empty[=private]
shared
private
shared-head
private-head
shared-footer
private-footer

Yes

Read input from one or more DocBook info files.

docinfodir

directory path

Yes

Location of docinfo files. Defaults to directory of source file if not specified.

docinfosubs

comma-separated substitution names
(attributes)

Yes

AsciiDoc substitutions that are applied to docinfo content.

doctype

article
book
inline
manpage

Yes

Output document type.

eqnums

empty[=AMS]
AMS
all
none

Yes

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. See equation numbering in MathJax.

hardbreaks-option

empty

Preserve hard line breaks.

hide-uri-scheme

empty

Hides URI scheme for raw links.

media

prepress
print
(screen)

Yes

Specifies media type of output and enables behavior specific to that media type. PDF converter only.

nofooter

empty

Yes

Turns off footer.

nofootnotes

empty

Yes

Turns off footnotes.

noheader

empty

Yes

Turns off header.

notitle

empty

Yes

Hides the doctitle in an embedded document. Mutually exclusive with the showtitle attribute.

outfilesuffix

file extension
ex. .html

Yes

File extension of output file, including dot (.), such as .html.

pagewidth

integer
(425)

Yes

Page width used to calculate the absolute width of tables in the DocBook output.

relfileprefix

empty
path segment

The path prefix to add to relative xrefs.

relfilesuffix

file extension
path segment
ex. .html

Yes

The path suffix (e.g., file extension) to add to relative xrefs. Defaults to the value of the outfilesuffix attribute. (Preferred over modifying outfilesuffix).

show-link-uri

empty

Prints the URI of a link after the link text. PDF converter only.

showtitle

empty

Yes

Displays the doctitle in an embedded document. Mutually exclusive with the notitle attribute.

stem

empty[=asciimath]
asciimath
latexmath

Yes

Enables mathematics processing and interpreter.

table-frame

(all)
ends
sides
none

Controls default value for frame attribute on tables.

table-grid

(all)
cols
rows
none

Controls default value for grid attribute on tables.

table-stripes

(none)
even
odd
hover
all

Controls default value for stripes attribute on tables.

tabsize

integer (≥ 0)

Converts tabs to spaces in verbatim content blocks (e.g., listing, literal).

webfonts

empty

Yes

Control whether webfonts are loaded when using the default stylesheet. When set to empty, uses the default font collection from Google Fonts. A non-empty value replaces the family query string parameter in the Google Fonts URL.

xrefstyle

full
short
basic

Formatting style to apply to cross reference text.

Image and icon attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`iconfont-cdn`	url (default CDN URL)	No	Yes	If not specified, uses the cdnjs.com service. Overrides CDN used to link to the Font Awesome stylesheet.
`iconfont-name`	any (`font-awesome`)	No	Yes	Overrides the name of the icon font stylesheet.
`iconfont-remote`	*empty*	Yes	Yes	Allows use of a CDN for resolving the icon font. Only relevant used when value of `icons` attribute is `font`.
`icons`	empty[=`image`] `image` `font`	No	Yes	Chooses images or font icons instead of text for admonitions. Any other value is assumed to be an icontype and sets the value to empty (image-based icons).
`iconsdir`	directory path url ex. ./images/icons	Yes	No	Location of non-font-based image icons. Defaults to the icons folder under `imagesdir` if `imagesdir` is specified and `iconsdir` is not specified.
`icontype`	`jpg` (`png`) `gif` `svg`	No	No	File type for image icons. Only relevant when using image-based icons.
`imagesdir`	*empty* directory path url	Yes	No	Location of image files.

iconfont-cdn

url
(default CDN URL)

Yes

If not specified, uses the cdnjs.com service. Overrides CDN used to link to the Font Awesome stylesheet.

iconfont-name

any
(font-awesome)

Yes

Overrides the name of the icon font stylesheet.

iconfont-remote

empty

Yes

Allows use of a CDN for resolving the icon font. Only relevant used when value of icons attribute is font.

icons

empty[=image]
image
font

Yes

Chooses images or font icons instead of text for admonitions. Any other value is assumed to be an icontype and sets the value to empty (image-based icons).

iconsdir

directory path
url
ex. ./images/icons

Yes

Location of non-font-based image icons. Defaults to the icons folder under imagesdir if imagesdir is specified and iconsdir is not specified.

icontype

jpg
(png)
gif
svg

File type for image icons. Only relevant when using image-based icons.

imagesdir

empty
directory path
url

Yes

Location of image files.

Source highlighting and formatting attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`coderay-css`	(`class`) `style`	No	Yes	Controls whether CodeRay uses CSS classes or inline styles.
`coderay-linenums-mode`	`inline` (`table`)	No	No	Sets how CodeRay inserts line numbers into source listings.
`coderay-unavailable`	empty	No	Yes	Instructs processor not to load CodeRay. Also set if processor fails to load CodeRay.
`highlightjsdir`	directory path url (default CDN URL)	No	Yes	Location of the highlight.js source code highlighter library.
`highlightjs-theme`	highlight.js style name (`github`)	No	Yes	Name of theme used by highlight.js.
`prettifydir`	directory path url (default CDN URL)	No	Yes	Location of non-CDN prettify source code highlighter library.
`prettify-theme`	prettify style name (`prettify`)	No	Yes	Name of theme used by prettify.
`prewrap`	*empty*	Yes	No	Wrap wide code listings.
`pygments-css`	(`class`) `style`	No	Yes	Controls whether Pygments uses CSS classes or inline styles.
`pygments-linenums-mode`	(`table`) `inline`	No	No	Sets how Pygments inserts line numbers into source listings.
`pygments-style`	Pygments style name (`default`)	No	Yes	Name of style used by Pygments.
`pygments-unavailable`	empty	No	Yes	Instructs processor not to load Pygments. Also set if processor fails to load Pygments.
`rouge-css`	(`class`) `style`	No	Yes	Controls whether Rouge uses CSS classes or inline styles.
`rouge-linenums-mode`	`inline` (`table`)	No	No	Sets how Rouge inserts line numbers into source listings. `inline` not yet supported by Asciidoctor. See asciidoctor#3641.
`rouge-style`	Rouge style name (`github`)	No	Yes	Name of style used by Rouge.
`rouge-unavailable`	empty	No	Yes	Instructs processor not to load Rouge. Also set if processor fails to load Rouge.
`source-highlighter`	`coderay` `highlight.js` `pygments` `rouge`	No	Yes	Specifies source code highlighter. Any other value is permitted, but must be supported by a custom syntax highlighter adapter.
`source-indent`	integer	No	No	Normalize block indentation in source code listings.
`source-language`	source code language name	No	No	Default language for source code blocks.
`source-linenums-option`	empty	No	No	Turns on line numbers for source code listings.

coderay-css

(class)
style

Yes

Controls whether CodeRay uses CSS classes or inline styles.

coderay-linenums-mode

inline
(table)

Sets how CodeRay inserts line numbers into source listings.

coderay-unavailable

empty

Yes

Instructs processor not to load CodeRay. Also set if processor fails to load CodeRay.

highlightjsdir

directory path
url
(default CDN URL)

Yes

Location of the highlight.js source code highlighter library.

highlightjs-theme

highlight.js style name
(github)

Yes

Name of theme used by highlight.js.

prettifydir

directory path
url
(default CDN URL)

Yes

Location of non-CDN prettify source code highlighter library.

prettify-theme

prettify style name
(prettify)

Yes

Name of theme used by prettify.

prewrap

empty

Yes

Wrap wide code listings.

pygments-css

(class)
style

Yes

Controls whether Pygments uses CSS classes or inline styles.

pygments-linenums-mode

(table)
inline

Sets how Pygments inserts line numbers into source listings.

pygments-style

Pygments style name
(default)

Yes

Name of style used by Pygments.

pygments-unavailable

empty

Yes

Instructs processor not to load Pygments. Also set if processor fails to load Pygments.

rouge-css

(class)
style

Yes

Controls whether Rouge uses CSS classes or inline styles.

rouge-linenums-mode

inline
(table)

Sets how Rouge inserts line numbers into source listings. `inline` not yet supported by Asciidoctor. See asciidoctor#3641.

rouge-style

Rouge style name
(github)

Yes

Name of style used by Rouge.

rouge-unavailable

empty

Yes

Instructs processor not to load Rouge. Also set if processor fails to load Rouge.

source-highlighter

coderay
highlight.js
pygments
rouge

Yes

Specifies source code highlighter. Any other value is permitted, but must be supported by a custom syntax highlighter adapter.

source-indent

integer

Normalize block indentation in source code listings.

source-language

source code language name

Default language for source code blocks.

source-linenums-option

empty

Turns on line numbers for source code listings.

HTML styling attributes

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`copycss`	*empty* file path	Yes	Yes	Copy CSS files to output. Only relevant when the `linkcss` attribute is set.
`css-signature`	valid XML ID	No	Yes	Assign value to `id` attribute of HTML `<body>` element. Preferred approach is to assign an ID to document title.
`linkcss`	empty	No	Yes	Links to stylesheet instead of embedding it. Can’t be unset in SECURE mode.
`max-width`	CSS length (e.g. 55em, 12cm, etc)	No	Yes	Constrains maximum width of document body. Not recommended. Use CSS stylesheet instead.
`stylesdir`	directory path url `.`	Yes	Yes	Location of CSS stylesheets.
`stylesheet`	*empty* file path	Yes	Yes	CSS stylesheet file name. An empty value tells the converter to use the default stylesheet.
`toc-class`	valid CSS class name (`toc`) or (`toc2`) if toc=left	No	Yes	CSS class on the table of contents container.

copycss

empty
file path

Yes

Copy CSS files to output. Only relevant when the linkcss attribute is set.

css-signature

valid XML ID

Yes

Assign value to id attribute of HTML <body> element. Preferred approach is to assign an ID to document title.

linkcss

empty

Yes

Links to stylesheet instead of embedding it. Can’t be unset in SECURE mode.

max-width

CSS length (e.g. 55em, 12cm, etc)

Yes

Constrains maximum width of document body. Not recommended. Use CSS stylesheet instead.

stylesdir

directory path
url
.

Yes

Location of CSS stylesheets.

stylesheet

empty
file path

Yes

CSS stylesheet file name. An empty value tells the converter to use the default stylesheet.

toc-class

valid CSS class name
(toc) or (toc2) if toc=left

Yes

CSS class on the table of contents container.

Manpage attributes

The attribute in this section are only relevant when using the manpage doctype and/or backend.

Name Allowable Values Set By Default Header Only Notes

Name	Allowable Values	Set By Default	Header Only	Notes
`mantitle`	any	Based on content.	Yes	Metadata for man page output.
`manvolnum`	any	Based on content.	Yes	Metadata for man page output.
`manname`	any	Based on content.	Yes	Metadata for man page output.
`manpurpose`	any	Based on content	Yes	Metadata for man page output.
`man-linkstyle`	link format pattern (`blue R <>`)	No	Yes	Link style in man page output.
`mansource`	any	No	Yes	Source (e.g., application and version) the man page describes.
`manmanual`	any	No	Yes	Manual name displayed in the man page footer.

mantitle

any

Based on content.

Yes

Metadata for man page output.

manvolnum

any

Based on content.

Yes

Metadata for man page output.

manname

any

Based on content.

Yes

Metadata for man page output.

manpurpose

any

Based on content

Yes

Metadata for man page output.

man-linkstyle

link format pattern
(blue R <>)

Yes

Link style in man page output.

mansource

any

Yes

Source (e.g., application and version) the man page describes.

manmanual

any

Yes

Manual name displayed in the man page footer.

Security attributes

Since these attributes deal with security, they can only be set from the API or CLI.

Name Allowable Values Set By Default API/CLI Only Notes

Name	Allowable Values	Set By Default	API/CLI Only	Notes
`allow-uri-read`	empty	No	Yes	Allows data to be read from URLs.
`max-attribute-value-size`	integer (≥ 0) `4096`	If safe mode is SECURE	Yes	Limits maximum size (in bytes) of a resolved attribute value. Default value is only set in SECURE mode. Since attributes can reference attributes, it’s possible to create an output document disproportionately larger than the input document without this limit in place.
`max-include-depth`	integer (≥ 0) `64`	Yes	Yes	Curtail infinite include loops and to limit the opportunity to exploit nested includes to compound the size of the output document.

allow-uri-read

empty

Yes

Allows data to be read from URLs.

max-attribute-value-size

integer (≥ 0)
4096

If safe mode is SECURE

Yes

Limits maximum size (in bytes) of a resolved attribute value. Default value is only set in SECURE mode. Since attributes can reference attributes, it’s possible to create an output document disproportionately larger than the input document without this limit in place.

max-include-depth

integer (≥ 0)
64

Yes

Curtail infinite include loops and to limit the opportunity to exploit nested includes to compound the size of the output document.

^[1] The -number attributes are created and managed automatically by the AsciiDoc processor 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 Asciidoctor, setting the -number attributes will influence the next number used for subsequent numbered blocks of that type. However, you should not rely on this behavior as it is subject to change in future revisions of the language.