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
&#160;

 

zwsp^[4]^
&#8203;

wj^[5]^
&#8288;

apos
&#39;

'

quot
&#34;

"

lsquo
&#8216;

rsquo
&#8217;

ldquo
&#8220;

rdquo
&#8221;

deg
&#176;

°

plus
&#43;

+

brvbar
&#166;

¦

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., &#34;) 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., &euro; 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., &#8364;).

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