Assign Attributes to a Site

You can apply attributes to all of the pages in a site by declaring them in a site’s playbook file.

Site attributes

Attributes declared in a playbook are referred to as site attributes. These attributes are set and available (or unavailable if unset) to all the pages in the site. The pages in a site are defined as all pages that Antora finds in the content sources specified in the playbook for a single run of Antora. Site attributes can be built-in, custom, and page attributes. The attribute precedence rules determine whether site attributes can be overridden at a more granular level.

In addition to being declared site-wide in a playbook, attributes can be defined per component version in an antora.yml file or directly on a page in the page’s header. However, when an attribute is hard set or hard unset in the site’s playbook, it overrides any subsequent declarations of the same attribute in a component version descriptor or page. Site attributes can also be configured from the CLI.

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.

attributes key

Site attributes are mapped under the attributes key in a playbook. The attributes key must be set under the asciidoc key.

Example 1. antora-playbook.yml
asciidoc:
  attributes:
    hide-uri-scheme: ''
    page-team: Coco B
    table-caption: ~
    listing-caption: Snippet@

Site attributes are applied and available to all of a site’s pages according to the attribute precedence rules.

Set attributes in the playbook

Each site attribute is entered on its own line as a key-value pair under the attributes key.

Example 2. Declare attributes in the playbook
asciidoc: (1)
  attributes: (2)
    listing-caption: Snippet (3)
    hide-uri-scheme: '' (4)
    page-team: Coco B (5)
    db: graphical-peaks-pack.db (6)
1 Enter the asciidoc key, followed by a colon (:), and press Enter.
2 The attributes key is nested under the asciidoc key. Enter attributes, followed by a colon (:), and press Enter.
3 Site attributes are nested under the attributes key. Enter the name of the attribute, followed by a colon (:). Press spacebar once after the colon, then enter 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 spacebar once after the colon, then enter the value of the attribute.
6 This custom attribute, like the previous three attributes, is hard set.

The attributes in Example 2 are all hard set. Hard set site attributes cannot be overridden from a component version descriptor or 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 component version or page to modify or unset a site attribute, you need to soft set the site attribute.

Attributes set in the playbook are site-wide and, thus, available to every page in your site. The values of custom attributes, such as page-team and db can be displayed in a page using the attribute reference syntax (e.g., {page-team}, {db}).

Soft set attributes

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

Example 3. Assign soft set precedence to attributes
asciidoc:
  attributes:
    page-team: Coco B@ (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 site attributes in Example 3 are soft set, a component version descriptor or page could modify their values or unset them.

Unset attributes in the playbook

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

Example 4. Hard unset site attributes in the playbook
asciidoc:
  attributes:
    figure-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 site attribute.
2 Boolean attributes are also hard unset when assigned the tilde symbol (~).

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

Soft unset attributes

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

Example 5. Assign soft unset precedence to attributes
asciidoc:
  attributes:
    figure-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 site attributes in Example 5 are soft unset, a component version descriptor or page could reset them.

Precedence rules

Antora takes the precedence assigned to attributes in the site’s playbook into account first. Site attributes that are hard set and hard unset can’t be changed by a component version descriptor file or a page. However, soft set and unset site attributes can be overridden from the component version descriptor or a page.

  1. Hard setting a site attribute using a string value with no trailing @ modifier (e.g., value or '') prevents a component version descriptor or page from changing or unsetting the attribute.

  2. Soft setting a site attribute using a string value with a trailing @ modifier (e.g., value@ or '@') allows a component version descriptor or page to change or unset the attribute.

  3. Hard unsetting a site attribute using the tilde symbol (~) prevents a component version descriptor or page from setting the attribute.

  4. Soft unsetting a site attribute using the false value allows a component version descriptor or page to set the attribute.

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

Intrinsic site attributes

Antora defines intrinsic site and page attributes from some of the keys in a playbook file. For instance, Antora sets the built-in attribute site-title and assigns it the value specified by the site.title key. Antora also sets some built-in AsciiDoc attributes, such as sectanchors, by default. See Site and configuration attributes and Intrinsic page 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.