AsciiDoc Attributes in Antora
Like the AsciiDoc processor, Antora uses AsciiDoc document attributes (herein attributes) to circulate information in and out of pages. These attributes are used to toggle or configure processing settings, control behavior and styles of the output, pass metadata from the source to the UI templates, and pass down information about the page to the content, among a variety of other uses.
In general, there are two kinds of attributes: built-in and custom. Attributes can also be divided into those that are page attributes and those that are not. This page introduces these attribute categories and refers you to additional pages to learn about how they’re defined and used.
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.,
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.
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.
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.
Where things get interesting is when the name of the attribute starts with
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
Or you can define your own page attribute named
page-edition and refer to it in the page using
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
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.