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.
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.
Component version attributes are set in a component version’s antora.yml file.
attributes keys must be set.
Then, each component version attribute is entered on its own line as a key-value pair under
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
|3||Each component version attribute is nested under the
|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 (
|5||To declare a custom page attribute, type
|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.,
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.,
~) 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 component version attributes can be overridden from a page.
An attribute is soft set by attaching the
@ modifier to the end of its value.
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
|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
Since the component version attributes in Example 2 are soft set, a page could modify their values or unset them.
Attributes can also be unset.
Component version attributes are hard unset when they’re assigned the reserved tilde symbol (
Each attribute is entered on its own line as a key-value pair under the
asciidoc: attributes: table-caption: ~ (1) hide-uri-scheme: ~ (2)
|1||To hard unset an attribute, assign it the tilde symbol (
|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 component version attributes can be overridden from a page.
An attribute is soft unset by assigning it the reserved value
asciidoc: attributes: table-caption: false (1) hide-uri-scheme: false (2)
|1||To soft unset an attribute, assign it the value
|2||Boolean attributes are also soft unset when assigned
Since the attributes in Example 4 are soft unset, a page could reset them.
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
'') prevents a page from changing or unsetting the attribute.
Soft setting a component version attribute using a string value with a trailing
'@') 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
falsevalue allows a page to set the attribute.
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
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