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 output, and pass down information about the page to the content, among a variety of other uses.

In general, there are two categories of attributes: built-in and custom. This page introduces these two categories of attributes, explains how attributes are defined in a page, and refers you to the pages that cover each category in more depth.

Built-in attributes

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. These built-in attributes have reserved names and serve a special, predefined purpose.

Attributes designed to be modified may be set from the CLI, in the playbook, in the component version descriptor, or in the page. If the attribute is set in the page, it must be defined in the page header using an attribute entry.

Many modifiable built-in attributes have a restricted set of accepted values. These attributes usually do two things; they toggle a behavior on or off, and they further accept information that alters how the output is generated. For example, the xrefstyle attribute controls the style of the linked text of internal xrefs (e.g., basic, short, or full).

The AsciiDoc processor defines numerous built-in attributes. Antora introduces additional built-in attributes that are only relevant in the Antora environment. Several of these attributes configure the AsciiDoc processor to work in the Antora environment, but most of them are page attributes. Page attributes are attributes prefixed with page-. They’re special in that they get promoted to the page UI model so they can be accessed from the UI templates. Page attributes open up the door of passing metadata to the UI template using custom attributes.

Custom 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 a custom attribute is defined as a page attribute. A custom page attribute allows the author to pass additional information about a page to the UI templates (thus not limited to the page itself).

Custom attributes can be defined from the CLI, in the playbook, in the component version descriptor, or in header of a page using an attribute entry. See Define a custom AsciiDoc attribute and Define a custom page attribute to learn how to define your own custom attributes.

What’s an attribute entry?

Before you can use a modifiable built-in attribute or custom attribute, you have to declare it. An attribute entry is the primary mechanism for activating the attribute and assigning it a value in a page. It’s like a global variable assignment for AsciiDoc.

An attribute entry consists of two parts: a name and a value. Each attribute entry must be entered on its own line in a page header. An attribute entry starts with an opening colon (:), directly followed by the attribute’s name, and then a closing colon (:). This activates, or sets, the attribute so you can use it in your page.

= Page Title
: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 an 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.

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

Some built-in AsciiDoc attributes don’t require a value to be explicitly assigned in an attribute entry because they’re a boolean attribute or have a default value.

= Page Title
: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 (:).

The values of built-in boolean attributes are always blank because their only accepted value is an empty string. Other built-in attributes may have a default value. If you set a built-in attribute and leave its value blank, Antora assigns the default value (if it has one) to the attribute at processing time.

Attribute precedence rules

Attributes can be scoped to a whole site by declaring them in a site’s playbook file. You can apply attributes to all of the pages in a component version by declaring them in its antora.yml file. Hard set and hard unset site and component version attributes take precedence over attributes defined on a page.

See the precedence rules for site attributes and component version attributes for more information.