AsciiDoc Attributes in Antora

Built-in attributes are AsciiDoc document attributes that either pass information to the page or provide a way for the author to toggle or configure behavior. Some built-in attributes are read-only, while others are meant to be modified.

Built-in attributes have reserved names and serve a special, predefined purpose. For example, the idseparator attribute is used to control the word separator for auto-generated section IDs. Although the purpose of a built-in attribute is restricted, like all AsciiDoc attributes, its value can be displayed on the page using an attribute reference (e.g., {idseparator}).

Many modifiable built-in attributes have a restricted set of acceptable values. Each value represents either a predefined behavior or a boundary condition. For example, the xrefstyle attribute controls the style of the linked text of internal xrefs using the predefined values basic, short, or full. The max-include-depth attribute specifies how deep includes can be nested.

The AsciiDoc processor defines numerous built-in attributes (not all of which apply to Antora). Antora introduces additional built-in attributes that are specific to the Antora environment. The purpose of these attributes is to configure the AsciiDoc processor to work with Antora. In most cases, these attributes are prefixed with page-, which makes them intrinsic page attributes.

Refer to Intrinsic attributes for a list of the read-only attributes defined by Antora. Refer to the AsciiDoc attribute catalog for a list of all built-in attributes defined in AsciiDoc (though keep in mind that not all of them are relevant in the Antora environment).

Custom attributes are AsciiDoc document attributes defined by the author. You may be familiar with using custom attributes in AsciiDoc to store reusable content, such as a URL or product name. The value of a custom attribute can then be used within the page (or across pages, depending on where it’s defined) using an attribute reference. Custom attributes work the same way in Antora.

See Define a custom AsciiDoc attribute and Define a custom page attribute to learn how to define your own custom attributes.

Where things get interesting is when the name of the attribute starts with page-. In this case, the attribute becomes a page attribute.

To the AsciiDoc document, page attributes are just like any other attribute. For example, you can refer to the component for the current page using built-in page attribute {page-version}. Or you can define your own page attribute named page-edition and refer to it in the page using {page-edition}.

What’s different about page attributes is that they get promoted to the page UI model so they can be accessed from a UI template (using the expression page.attributes.<name>). Thus, a page attribute allows the author to pass metadata about a page to the UI, thus allowing it to be used outside of the AsciiDoc content. It’s even possible to read page attributes from other pages in the UI template. Attributes that are not prefixed with page- are not accessible in this way.

While page attributes are primarily custom attributes, Antora defines a handful of built-in page attributes to control Antora-specific features or get information about the current page. See Page Attributes to learn more about page attributes, and how to define and use them.