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.

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 kbd:[Enter].
2	Nest the `attributes` key on the line directly underneath the `asciidoc` key. Type `attributes`, followed by a colon (`:`), and press kbd:[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 kbd:[spacebar] once after the colon, then type the value of the attribute.
4	To assign the default value, or in the case of a boolean attribute, the empty string value, to a built-in attribute, type two consecutive single quotation marks (`''`) in the value field.
5	To declare a custom page attribute, type `page-` and the name of your attribute, followed by a colon (`:`). Press kbd:[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.

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 3. Hard unset attributes

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

1	To hard unset an attribute, assign it the tilde symbol (`~`). The `~` is a reserved value that hard unsets a component version 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 4. 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 4 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. 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.