Document Attributes Reference

Built-in document attributes can be set anywhere in the document using an attribute entry . 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 command line or API, it’s defined for the whole document and cannot be changed in the body unless @ is added to the end of the value. (The one exception to this rule is the sectnums attribute, which can always be changed).

  • If you set an attribute in the body (anywhere after the document header), the attribute is visible from the point it is set until it is unset (assuming it is not locked as a result of being set from the command line or API).

Several attributes from AsciiDoc Python have been deprecated in Asciidoctor and therefore are not included in this section. See Migrating from AsciiDoc Python to Asciidoctor if you are updating an older document.
Attribute name Description Default value[1] Allowed values Header only See also

Compliance

attribute-missing

Controls how missing references are handled.

skip

skip, drop, drop-line or warn

[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

Yes

[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

Yes

Internationalization and numbering

appendix-caption

Sets the text used to prefix appendix titles.

Appendix

any

[user-appendix], [customizing-labels]

appendix-number

Stores the number (aka letter) for the current appendix.[2]

A

letter

appendix-refsig

Sets the signifier added to the title of appendices in cross reference text. Unset to disable.

Appendix

any

[book-parts-and-chapters], [sections], [customizing-labels]

caution-caption

Sets the text used to label CAUTION admonitions when icons are not enabled.

Caution

any

[admonition], [customizing-labels]

chapter-number

Stores the number for the current chapter.[2]

2

integer

chapter-refsig

Sets the signifier added to the title of numbered chapters in cross reference text. Unset to disable.

Chapter

any

[book-parts-and-chapters], [sections], [customizing-labels]

chapter-label

Sets the prefix added to chapter titles (i.e., level-1 section titles when doctype is book). (pdf converter only)

Chapter

any

[book-parts-and-chapters], [sections], [customizing-labels]

example-caption

Sets the text used to label example blocks.

Example

any

[customizing-labels]

example-number

Stores the number for the current numbered example.[2]

5

integer

figure-caption

Sets the text used to label figures.

Figure

any

[images], [customizing-labels]

figure-number

Stores the number for the current numbered figure.[2]

3

integer

important-caption

Sets the text used to label IMPORTANT admonitions when icons are not enabled.

Important

any

[admonition], [customizing-labels]

lang

Set the value of the lang attribute on the root element of the output document.

en

Valid XML country code

Yes

[customizing-labels]

last-update-label

Text label for the “Last updated” time in the footer. Unsetting it will remove the label and time from the footer.

Last updated

any

Yes

[footer-docinfo-files], [customizing-labels]

listing-caption

Sets the text used to label listing blocks.

not set

any

[customizing-labels]

listing-number

Stores the number for the current numbered listing.[2]

5

integer

manname-title

Label for the program name section in the manpage.

NAME

any

Yes

[customizing-labels]

nolang

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

not set

empty

Yes

note-caption

Sets the text used to label NOTE admonitions when icons are not enabled.

Note

any

[admonition], [customizing-labels]

preface-title

Sets the title text for an anonymous preface when the doctype is book.

not set

any

[user-preface]

section-refsig

Sets the signifier added to the title of numbered sections in cross reference text. Unset to disable.

Section

any

[book-parts-and-chapters], [sections], [customizing-labels]

table-caption

Text of the label that is automatically prefixed to table titles. To turn off table caption labels and numbers, add the table-caption attribute to the document header with an empty value.

Table

any

[customizing-labels]

table-number

Stores the number for the current numbered table.[2]

5

integer

tip-caption

Sets the text used to label TIP admonitions when icons are not enabled.

Tip

any

[admonition], [customizing-labels]

toc-title

Title for the table of contents.

Table of Contents

any

[user-toc], [customizing-labels]

untitled-label

Used as the default document title if the document does not have a document title.

Untitled

any

Yes

[customizing-labels]

version-label

The label preceding the revnumber in a converted document’s byline

Version

any

Yes

[revision-number-date-and-remark], [customizing-labels]

warning-caption

Sets the text used to label TIP admonitions when icons are not enabled.

Warning

any

[customizing-labels]

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

Yes

author

Sets the document’s main author. Can be set automatically via the author info line.

not set

any

Yes

[doc-header]

authorinitials

Sets the author’s initials (e.g., JD). Derived automatically from the author attribute by default.

not set

any

Yes

[doc-header]

authors

Sets the document authors as a comma-separated list. Can be set automatically via the author info line. If set, adds an author meta element inside the HTML document head.

not set

any

Yes

[metadata]

copyright

If set, adds a copyright meta element inside the HTML document head.

not set

any

Yes

[metadata]

doctitle

Sets the document title. Set automatically to section title if document begins with level-0 section.

Based on content.

any

Yes

[document-title]

description

If set, adds a description meta element inside the HTML document head.

not set

any

Yes

[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

Yes

[doc-header]

firstname

Sets the author’s first name. Can be set automatically via the author info line.

not set

any

Yes

[doc-header]

front-matter

If skip-front-matter is set, holds any YAML-style frontmatter skimmed from the top of the document.

Front matter content, if captured.

any

Yes

[front-matter-added-for-static-site-generators]

keywords

If set, adds a keywords meta element inside the HTML document head.

not set

any

Yes

[metadata]

lastname

Sets the author’s last name. Can be set automatically via the author info line.

not set

any

Yes

[doc-header]

middlename

Sets the author’s middle name or initial. Can be set automatically via the author info line.

not set

any

Yes

[doc-header]

orgname

If set, add an <orgname> element with this value to the DocBook info element.

not set

any

Yes

[metadata]

revdate

Sets the revision date. Can be set automatically via the revision info line.

not set

any

Yes

[doc-header]

revremark

Sets the revision description. Can be set automatically via the revision info line.

not set

any

Yes

[doc-header]

revnumber

Sets the revision number. Can be set automatically via the revision info line.

not set

any

Yes

[doc-header]

title

Sets the value of the <title> element in the HTML <head> or main DocBook <info> of the output document. Also used as a fallback when the document title is not specified. Since this is a reserved attribute that has special behavior, you should avoid using it for any other purpose!

not set

any

Yes

[document-title]

Section titles and table of contents

idprefix

Sets prefix used for auto-generated section IDs.

_

Valid XML ID start character.

Yes

[auto-generated-ids]

idseparator

Sets word separator used in auto-generated section IDs.

_

Valid XML ID character.

Yes

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

[include-partitioning]

sectanchors

If set, adds an anchor in front of the section title when the mouse cursor hovers over it.

not set (No anchors).

empty

Yes

[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

Yes

[auto-generated-ids]

sectlinks

Turns section titles into self-referencing links.

not set

empty

Yes

[links]

sectnums

If set, numbers sections to depth specified by sectnumlevels.

not set (Sections are not numbered).

empty

Yes

[numbering]

sectnumlevels

controls the depth of section numbering

3

0–5

Yes

[numbering-depth]

title-separator

The character used to separate the main title and subtitle in the document title.

:

any

Yes

[subtitle-partitioning]

toc

Switches the table of contents on, and defines its location.

not set

auto, left, right, macro or preamble

Yes

[user-toc]

toclevels

Maximum section level to display.

2

1–5

Yes

[user-toc]

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

Yes

cache-uri

If set, cache content read from URIs.

not set

empty

Yes

[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

Yes

[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

Yes

[naming-docinfo-files]

docinfodir

The location where docinfo files are resolved.

The base directory.

Directory

Yes

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

Yes

[attribute-substitution-in-docinfo-files]

doctype

Set the output document type.

article

article, book, inline or manpage

Yes

[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

Yes

[stem], Equation numbering in MathJax

hardbreaks

Preserve hard line breaks in the input.

not set

empty

[line-breaks]

hide-uri-scheme

Hides the URI scheme for all raw links.

not set

empty

[url]

linkattrs

Parse attributes inside the link macro.

not set (Do not parse).

empty

[url]

media

Specifies the media type of the output, which may enable behavior specific to that media type.

screen

screen or print

Yes

nofooter

Suppresses output of the footer.

not set

empty

Yes

[footer-docinfo-files]

nofootnotes

Turn off display of footnotes.

not set

empty

Yes

[user-footnotes]

noheader

Suppresses output of the header.

not set

empty

Yes

[doc-header]

outfilesuffix

File extension of the output file (starting with a period).

Determined by the backend (.html for html, .xml for docbook, etc).

File extension

[navigating-between-source-files]

pagewidth

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

425

Number

Yes

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

Yes

showtitle

If set, displays an embedded document’s title. Mutually exclusive with the notitle attribute.

not set

empty

Yes

[document-title]

stem

Enables mathematics processing or sets the processor used.

not set

empty (defaults to asciimath), asciimath or latexmath

Yes

[stem-in]

tabsize

If set, converts tabs to spaces in verbatim content blocks (e.g., listing, literal).

not set

0 or more

-

webfonts

Control whether webfonts are loaded, and which ones, when using the default stylesheet. The value populates the family query string parameter in the Google Fonts URL.

empty (use default fonts)

empty or a Google Fonts collection spec

Yes

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

Yes

[docbook]

xrefstyle

The formatting style to apply to cross reference text. Introduced in 1.5.6.

not set

full, short, or basic

Yes

[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

Yes

[icons]

iconfont-name

Overrides the name of the icon font stylesheet. Only used when icons attribute is set to font.

font-awesome

any

Yes

[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

Yes

[icons]

icons

Chooses icons instead of text for admonitions.

not set (image)

font or image

Yes

[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

Yes

[icons]

icontype

File type for image icons. Only used when icons attribute is set to image.

png

any, but typically jpg, tiff, etc.

Yes

[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

Yes

[coderay]

coderay-linenums-mode

Sets how CodeRay inserts line numbers into source listings.

table

table or inline

Yes

[coderay]

coderay-unavailable

If set, tells the processor not to attempt to load CodeRay.

not set

empty

Yes

[coderay]

highlightjsdir

Location of the highlight.js source code highlighter library.

not set

Directory

Yes

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

Yes

[highlight-js]

prettifydir

Location of the prettify source code highlighter library.

not set (Uses CDN).

Directory

Yes

[source-code-blocks]

prettify-theme

Sets the name of the theme used by the prettify source code highlighter.

prettify

A style name recognized by prettify.

Yes

[source-code-blocks]

prewrap

Wrap wide code listings. Sets the default behavior only; you can still switch off wrapping on specific listings.

empty (Code listing will wrap long lines, not scroll).

empty

[to-wrap-or-to-scroll]

pygments-css

Controls whether Pygments uses CSS classes or inline styles.

class

class or style

Yes

[pygments]

pygments-linenums-mode

Sets how Pygments inserts line numbers into source listings.

table

table or inline

Yes

[pygments]

pygments-style

Sets the name of the style used by the Pygments source code highlighter

default

A style name recognized by Pygments.

Yes

[pygments]

pygments-unavailable

If set, tells the processor not to attempt to load Pygments.

not set

empty

Yes

[pygments]

source-highlighter

Source code highlighter to use.

not set

coderay, highlightjs, prettify or pygments

Yes

[source-code-blocks]

source-indent

Normalize block indentation in code listings.

not set (Indentation is not modified).

Number

[normalize-block-indentation]

source-language

Set the default language for source code listings.

not set

Code language name in lowercase.

[source-code-blocks]

source-linenums-option

Turns on line numbers option by default for source code listings. Introduced in 1.5.6.

not set

empty

[source-code-blocks]

HTML styling

copycss

If set, copy the CSS files to the output.

empty (File is copied if linkcss is set).

Empty or the location of the custom stylesheet (if used)

Yes

[applying-a-theme]

css-signature

If set, assign the value to the id attribute of the <body> element (HTML only). The preferred approach is to assign an ID to the document title.

not set

Valid XML ID

Yes

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

Yes

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

Yes

stylesdir

Location for resolving CSS stylesheets.

. (Same directory as document).

Directory

Yes

[creating-a-theme]

stylesheet

Name of a CSS stylesheet to replace the default one.

not set (The default stylesheet is used).

File name

Yes

[applying-a-theme]

toc-class

The CSS class on the table of contents container.

toc

Valid CSS class name

Yes

[user-toc]

Manpage attributes (relevant only when using the manpage doctype and/or converter)

mantitle

Metadata for manpage output.

Based on content.

any

Yes

[man-pages]

manvolnum

Metadata for manpage output.

Based on content.

any

Yes

[man-pages]

manname

Metadata for manpage output.

Based on content.

any

Yes

[man-pages]

manpurpose

Metadata for manpage output.

Based on content.

any

Yes

[man-pages]

man-linkstyle

Style the links in the manpage output.

blue R <>

Link format sequence

Yes

[man-pages]

mansource

The source (e.g., application and version) to which the manpage pertains.

not set

any

Yes

[man-pages]

manmanual

Manual name displayed in the manpage footer.

not set

any

Yes

[man-pages]

Secure attributes (can only be set from the command line or API, typically for security reasons)

allow-uri-read

If set, allows data to be read from URIs (via include directive, image macro when embedding images, etc.).

not set

empty

CLI or API

[include-uri]

max-attribute-value-size

Limits the maximum size (in bytes) of a resolved attribute value. Since attributes can reference other attributes, it would be possible to create an output document disproportionately larger than the input document without this limit in place.

4096 (secure mode), not set (other modes)

0 or greater

CLI or API

max-include-depth

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

64

0 or greater

CLI or API

[include-directive]

skip-front-matter

If set, consume YAML-style frontmatter at the top of the document and store it in the front-matter attribute.

not set

empty

CLI or API

[front-matter-added-for-static-site-generators]

[1] The default value isn’t necessarily the value you will get by entering {name}. It may be the fallback value which Asciidoctor uses if the attribute is not defined. The effect is the same either way.

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