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. 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 Document Attributes Reference 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-. With this special designation, the attribute becomes a page attribute.

To the AsciiDoc document, page attributes are just like any other AsciiDoc 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}. In this context, the page- prefix is not significant.

Where this special designation comes into play is when the UI template is applied to the page’s contents. Page attributes get promoted to the page’s UI model so they can be accessed using the expression page.attributes.<name> within a UI template (e.g., layouts/default.hbs). In effect, a page attribute allows the author to pass metadata defined using attributes either in the page’s header or in a configuration file (e.g., the Antora playbook), thus allowing that information to be used outside of the AsciiDoc document. It’s even possible to access page attributes from pages other than the current page in the UI template. Attributes that are not prefixed with page- are not accessible in this way (though it’s still possible to access all attributes using a UI helper).

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.