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.

Take note that header substitutions automatically get applied to the value by default. That means you don’t need to escape special characters such in an HTML tag. It also means you can reference the value of attributes which have already been defined when defining the value of an attribute. Attribute references in the value of an attribute entry are resolved immediately.

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 an implied value.

When set, the value of a built-in boolean attribute is always empty (i.e., an empty string). If you set a built-in attribute and leave its value empty, the AsciiDoc processor may infer a value at processing time.

An attribute entry is most often declared in the document header. For attributes that allow it (which includes general purpose attributes), the attribute entry can alternately be declared between blocks in the document body (i.e., the portion of the document below the header).

When an attribute is defined in the document header using an attribute entry, that’s referred to as a header attribute. A header attribute is available to the entire document until it is unset. A header attribute is also accessible from the document metadata for use by built-in behavior, extensions, and other applications that need to consult its value (e.g., source-highlighter).

When an attribute is defined in the document body using an attribute entry, that’s simply referred to as a document attribute. For any attribute defined in the body, the attribute is available from the point it is set until it is unset. Attributes defined in the body are not available via the document metadata.

Unless the attribute is unlocked, it can be unset or assigned a new value in the document header or body. However, note that unsetting or redefining a header attribute that controls behavior in the document body usually has no affect. See the Document Attributes Reference for where in a document each attribute can be set.

Document attributes can also be declared (set with an optional value or unset) outside the document via the CLI and API. The attribute entry syntax is not used in these cases. Rather, they are declared using the provided option. For the API, attributes are declared using the :attributes option (which supports various entry formats). For the CLI, the attribute is declared using the -a option.

When an attribute is assigned a value outside of the document, the value is stored as is, meaning substitutions are not applied to it. That also means that the special characters and quote substitutions are not applied to the value of that attribute when it is referenced in the document. However, subsequent substitutions, such as the macro substitution, do get applied. This behavior is due to that fact that the attributes substitution is applied after the special characters and quote substitutions. In order to force these substitutions to be applied to the value of the attribute, you must alter the substitution order at the point of reference. Here’s an example using the inline pass macro.

When an attribute is declared from the command line or API, it is implicitly a document header attribute. By default, the attribute becomes locked (i.e., hard set or unset) and thus cannot be changed by the document. This behavior can be changed by adding an @ to the end of the attribute name or value (i.e., the soft set modifier). See Document Attribute Assignment Precedence for more information.

The one exception to this rule is the sectnums attribute, which can always be changed.