Attribute Entries

What is an attribute entry?

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.

:name-of-an-attribute: (1)
1 The attribute’s name is directly preceded with a opening colon (:) and directly followed by a closing colon (:).

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.

:name-of-an-attribute: value of the attribute (1)
1 An explicitly assigned value is offset from the closing colon (:) by at least one space. At the end of the value, press Enter.

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.

:url-org: https://example.org/projects
:url-project: {url-org}/project-name (1)
1 You can reuse the value of an attribute which has already been set using using an attribute reference in the value.

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.

:name-of-an-attribute: (1)
1 If you don’t want to explicitly assign a value to the attribute, press Enter after the closing colon (:).

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.

Where can an attribute entry be declared?

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

An attribute entry should not be declared inside the boundaries of a delimited block. When an attribute entry is declared inside a delimited block, the behavior is undefined.

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.

Defining document attributes without an attribute entry

Document attributes can also be set, assigned values, and unset via the CLI and API. 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. These attributes are implicitly header attributes. See Document Attribute Assignment Precedence for more information. The one exception to this rule is the sectnums attribute, which can always be changed.