Assign Attributes to a Component Version

You can apply attributes to all of the pages in a component version by declaring them in the antora.yml file for that component version.

Component version attributes

Attributes that are defined in a component version descriptor are referred to as component version attributes. Component version attributes can be built-in, custom, and page attributes. These attributes are applied and available (or made unavailable if unset) to all of a component version’s pages according to the attribute precedence rules. If an attribute was previously hard set or hard unset in the site’s playbook, its declaration in a component version descriptor will have no impact.

Playbook file versus component version descriptor file

Attributes are declared using the same structure and syntax in both the playbook file and the component version descriptor file.

The playbook is where you configure the site, content sources, and UI URLs. A playbook file usually has the word playbook in its filename, e.g., antora-playbook.yml or local-antora-playbook.yml.

A component version descriptor is where you configure the name, version, metadata, attributes, and navigation list of a component version. A component version descriptor’s filename is always antora.yml.

For extension writers. If no AsciiDoc attributes are defined in the component descriptor, the asciidoc property on the component version object will reference the site-wide AsciiDoc config object (i.e., siteAsciiDocConfig). If you plan to modify component version attributes, first check if the value of the asciidoc property matches (===) the site-wide object and make a deep copy of it if so.

Set attributes in antora.yml

Component version attributes are set in a component version’s antora.yml file. First, the asciidoc and attributes keys must be set. Then, each component version attribute is entered on its own line as a key-value pair under attributes.

Example 1. Declare attributes in antora.yml

name: light
title: Data Light
version: '2.3'
asciidoc: (1)
  attributes: (2)
    table-caption: Data Set (3)
    hide-uri-scheme: '' (4)
    page-level: Advanced (5)
    page-category: Statistics; Cloud Infrastructure (6)
nav:
- modules/ROOT/nav.adoc

1	On a new line, type `asciidoc`, followed by a colon (`:`), and press `Enter`.
2	Nest the `attributes` key on the line directly underneath the `asciidoc` key. Type `attributes`, followed by a colon (`:`), and press `Enter`.
3	Each component version attribute is nested under the `attributes` key and defined on its own line. Type the name of the attribute, followed by a colon (`:`). Press the `spacebar` once after the colon, then type the value of the attribute.
4	To set an attribute without specifying an explicit value, assign an empty string by entering two consecutive single quotation marks (`''`) in the value part. For certain built-in attributes, an empty value is equivalent to the default value, though it depends on the attribute. Although using the boolean value `true` often works in this case, attribute values in AsciiDoc are strings, so it will likely be coerced to the string value `'true'`.
5	To declare a custom page attribute, type `page-` and the name of your attribute, followed by a colon (`:`). Press `spacebar` once after the colon, then enter the value of the attribute.
6	When an attribute has multiple, independent values, separate each value with a semicolon (`;`).

A set component version attribute is applied and available to every page that belongs to the component version. The values of custom attributes, such as page-level, can be displayed in a page using the attribute reference syntax (e.g., {page-level}).

The attributes in Example 1 are all hard set. Hard set component version attributes cannot be overridden from a page. By default, an attribute is hard set when it’s assigned a value that isn’t reserved for unsetting the attribute (i.e., false or ~) and doesn’t end with a modifier (i.e., @). To allow a page to modify or unset a component version attribute, you need to soft set the component version attribute.

Soft set attributes

Soft set component version attributes can be overridden from a page. An attribute is soft set by attaching the @ modifier to the end of its value.

Example 2. Assign soft set precedence to attributes

asciidoc:
  attributes:
    table-caption: Data Set@ (1)
    hide-uri-scheme: '@' (2)

1	To soft set an attribute that’s assigned an explicit value, attach the `@` modifier to the end of its value.
2	To soft set and assign a built-in attribute’s default value, or in the case of a boolean attribute, the empty string value, type an opening single quotation mark, followed by the `@` modifier, and then a closing single quotation mark (`'`).

Since the component version attributes in Example 2 are soft set, a page could modify their values or unset them.

Insert the value of another attribute

The value of any component version attribute set earlier in the same antora.yml file or the value of any site attribute can be inserted into the value of a component version attribute using an AsciiDoc attribute reference (e.g., {site-title}, {page-level}).

Example 3. A component version attribute that references the value of another component version attribute

name: light
title: Data Light
version: '2.3'
asciidoc:
  attributes:
    table-caption: Data Set
    url-plugins: https://example.com/plugins
    url-data-plugin: {url-plugins}/data-light
nav:
- modules/ROOT/nav.adoc

A component version attribute can also be referenced in the value of a page attribute.

To prevent an attribute reference substitution in an attribute value, insert a backslash in front of the reference (e.g., \{not-substituted}). In this case, the attribute reference will not be substituted and the backslash will be omitted.

Unset attributes in antora.yml

Attributes can also be unset. Component version attributes are hard unset when they’re assigned the reserved tilde symbol (~) value. Each attribute is entered on its own line as a key-value pair under the attributes key.

Example 4. Hard unset attributes

asciidoc:
  attributes:
    table-caption: ~ (1)
    hide-uri-scheme: ~ (2)

1	To hard unset an attribute, assign it the tilde symbol (`~`). `~` is shorthand in YAML for `nil`, which is a reserved value that hard unsets a site attribute.
2	Boolean attributes are also hard unset when assigned the tilde symbol (`~`).

Hard unset component version attributes cannot be overridden from a page. When a component version attribute is hard unset, its behavior is turned off and it isn’t available to the component version’s pages.

Soft unset attributes

Soft unset component version attributes can be overridden from a page. An attribute is soft unset by assigning it the reserved value false.

Example 5. Assign soft unset precedence to attributes

asciidoc:
  attributes:
    table-caption: false (1)
    hide-uri-scheme: false (2)

1	To soft unset an attribute, assign it the value `false`.
2	Boolean attributes are also soft unset when assigned `false`.

Since the attributes in Example 5 are soft unset, a page could reset them.

Precedence rules

Antora takes the precedence assigned to site attributes into account first. An attribute declared in an antora.yml file cannot override the same attribute if it’s hard set or hard unset in a playbook. A component version attribute can override a site attribute only if the site attribute is soft set or unset.

When component version attributes are declared, you can control whether a page can reset or unset each attribute on a case by case basis. Assuming that the attribute was soft set or unset, or wasn’t previously defined in a playbook, then component version attributes that are hard set or hard unset can’t be changed by a page. However, soft set and unset component version attributes can be overridden from a page.

Hard setting a component version attribute using a string value with no trailing @ modifier (e.g., value or '') prevents a page from changing or unsetting the attribute.
Soft setting a component version attribute using a string value with a trailing @ modifier (e.g., value@ or '@') allows a page to change or unset the attribute.
Hard unsetting a component version attribute using the tilde symbol (~) prevents a page from setting the attribute.
Soft unsetting a component version attribute using a false value allows a page to set the attribute.

To learn more about how component version attributes interact with site attributes and page attributes, see Assign Attributes to a Site and AsciiDoc Attributes in Antora.

Intrinsic component version attributes

Antora defines intrinsic page attributes from most of the keys in a component version descriptor file. For instance, Antora sets the built-in attribute page-component-title and assigns it the value specified by the title key. These attributes cannot be referenced by other attributes defined in antora.yml, but can be referenced in any page within the same component version. See Intrinsic page attributes for a complete list of the page attributes Antora automatically declares.

Antora also sets some built-in AsciiDoc attributes, such as sectanchors, by default. See Site and configuration attributes for more information.

Some built-in AsciiDoc attributes are not applicable in the Antora environment. These attributes include data-uri, allow-uri-read, docinfo, linkcss, noheader, nofooter, webfonts, and outfilesuffix. Setting these attributes either has no effect or may cause Antora to malfunction. Other attributes, such as imagesdir, are automatically set by Antora and cannot be overridden.