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

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)

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).

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]

docyear

integer
ex. 2021

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).

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. 2021

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.

[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

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.

Localization and numbering attributes

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]

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.

Document metadata attributes

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.

Section title and table of contents attributes

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

General content and formatting attributes

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.

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.

Image and icon attributes

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.

Source highlighting and formatting attributes

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.

HTML styling attributes

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.

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

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.

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

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.

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