Declare Built-In Document Attributes

An AsciiDoc processor 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.

Use an attribute’s default value

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:

  1. it has a default value, and

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

Override an attribute’s default value

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 the AsciiDoc processor 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 book value.

= Title of My Document
:doctype: book (1)
1 Set doctype in the document header and assign it the value book. Explicit values must be offset from the closing colon (:) by at least one space.

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

Override a default asset directory value

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: ./stylesheets) and JavaScript files (default: ./javascripts).

Example 1. Replace the default values of the built-in asset directory attributes
= 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).