Attribute Entries

Before you can use a document attribute in your document, you have to declare it. An attribute entry is the primary mechanism for defining a document attribute in an AsciiDoc document. You can think of an attribute entry as a global variable assignment for AsciiDoc. The document attribute it creates becomes available from that point forward in the document. Attribute entries are also frequently used to toggle features.

An attribute entry consists of two parts: an attribute name and an attribute value. The attribute name comes first, followed by the optional value. Each attribute entry must be entered on its own line. An attribute entry starts with an opening colon (:), directly followed by the attribute’s name, and then a closing colon (:). This sets — that is, turns on — the document attribute so you can use it in your document.

In many cases, you explicitly assign a value to a document attribute by entering information after its name in the attribute entry. The value must be offset from the closing colon (:) by at least one space. Be aware that header substitutions automatically get applied to the value by default.

Some built-in attributes don’t require a value to be explicitly assigned in an attribute entry because they’re a boolean attribute or have a default value.

The values of built-in boolean attributes are always blank because their only accepted value is an empty string. Other built-in attributes may have a default value. If you set a built-in attribute and leave its value blank, Asciidoctor assigns the default value, if it has one, to the attribute at processing time.

An attribute entry is typically defined in the document header. When set in the document header, the attribute is available to the entire document until it is reset or unset. The attribute’s value can be reassigned or the attribute unset at any subsequent point in the document, unless the attribute is locked (typically by defining it using the CLI or API).

Many, but not all, document attributes can be set, assigned a value, or unset in the document’s body (anywhere below the document header). When you set an attribute in the body, it’s visible from the point it’s set until it’s unset. See the Document Attributes Reference for where in a document each attribute can be set.

Finally, document attributes can also be set, assigned values, and unset via the CLI and API, but these methods don’t use the attribute entry syntax. When an attribute is set from the command line or API, it’s defined for the whole document and can’t be changed in the document header or body unless @ is added to the end of the value. See Document Attribute Assignment Precedence for more information. The one exception to this rule is the sectnums attribute, which can always be changed.