Declare Built-In Document Attributes
Asciidoctor has numerous attributes reserved for special purposes. Built-in attributes add, configure, and control common features in a document. Many built-in attributes only take effect when defined in the document header with an attribute entry.
Many built-in attributes have a default value. When you want to activate a built-in attribute and assign it its default value, you can leave the value in the attribute entry empty.
For example, to turn on the Table of Contents for a document, you set the
toc attribute using an attribute entry in the document header.
= Title of Document :toc:
The default value of an activated attribute will be assigned at processing time, if:
it has a default value, and
the value in the attribute entry is left empty
In the example above, the default value of
auto will be assigned to
toc since the value was left empty in the attribute entry.
You may not want to use the default value of a built-in attribute.
In the next example, we’ll override the default value of an attribute that Asciidoctor sets automatically.
The built-in attribute
doctype is automatically set and assigned a value of
article at processing time.
However, if you want to use AsciiDoc’s book features, the
doctype attribute needs to be assigned the
= Title of My Document :doctype: book (1)
To override an attribute’s default value, you have to explicitly assign a value when you set the attribute. The value assigned to an attribute in the document header replaces the default value (assuming the attribute is not locked via the CLI or API).
You can also use the built-in asset directory attributes to customize the base path to images (default:
empty), icons (default:
./images/icons), stylesheets (default:
= My Document :imagesdir: ./images :iconsdir: ./icons :stylesdir: ./styles :scriptsdir: ./js
The four built-in attributes in the example above have default values that are automatically set at processing time. However, in the example, they’re being set and assigned explicit values in the document header. This explicit user-defined value replaces the default value (assuming the attribute is not locked via the CLI or API).