Define and Modify Attributes
With the exception of certain intrinsic attributes, which are read-only, any AsciiDoc document attribute (herein attributes) may be defined from the CLI, in the playbook, in the component descriptor, or in the header of a page using an attribute entry. The precedence matches that order (higher to lower) unless the precedence has been altered for a given attribute using a modifier. These different scopes give you the ability to define attributes at the level of granularity you need and to be able to override their values for different environments or situations.
This page explains how to define and modify an attribute at the page level using an attribute entry. Alternately, these attributes can be set at a higher level using the CLI, playbook, or component descriptor. The result of defining or modifying an attribute is the same (meaning the processor doesn’t care how it’s defined).
What’s an attribute entry?
An attribute entry is the primary mechanism for defining an attribute for a page and, if applicable, assigning a value to it. You can think of an attribute entry like a global variable assignment in 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 kbd:[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 kbd:[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.
Set a built-in attribute
Let’s activate the AsciiDoc attribute named sectanchors.
The attribute is set by entering its name in an attribute entry in the header of the page.
= Page Title
:sectanchors: (1)| 1 | The attribute is set in page header by directly preceding its name, sectanchors, with an opening colon (:) and directly following it with a closing colon (:). |
When set, sectanchors adds an anchor to the left of each section title.
sectanchors is a boolean attribute, so its value is an empty string.
Assign a value to a built-in attribute
In the next example, let’s assign a value to a built-in AsciiDoc attribute.
The attribute xrefstyle has three built-in values it can accept, short, full, and basic.
= Page Title
:xrefstyle: short (1)| 1 | Set xrefstyle in the page header and assign it the value short.
Explicit values must be offset from the closing colon (:) by at least one space. |
When the short value is assigned to xrefstyle, any in-page references to blocks with anchors will display the blocks’ label and number, e.g., Listing 1, if no link text is specified in the reference.
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.
|
Define a custom attribute
Custom attributes often store frequently used text and URLs. They’re then referenced throughout the page by simply entering their name (instead of repeatedly typing the text or URLs). Before they can be referenced, custom attributes must have a user-defined name and be assigned a value.
The attribute’s name must:
-
be at least one character long,
-
begin with a word character (A-Z, a-z, 0-9, or _), and
-
only contain word characters and hyphens, meaning the name cannot contain a dot (
.) or a space.
Although uppercase characters are permitted in an attribute name, the name is automatically converted to lowercase before being stored. A best practice is to only use lowercase letters in the name and avoid starting the name with a number.
Attribute values can:
-
be any inline content, and
-
contain line breaks, but only if an explicit line continuation (
+) is used.
In Example 2, a custom attribute’s name and value are defined using an attribute entry.
= Page Title
:url-repo: https://gitlab.com/antora/demo/docs-siteNow, you can reference the attribute wherever needed throughout the page by entering its name inside a set of curly braces ({attribute-name}).
You can see another example of a custom attribute being used to replace a complex URL in Create an attribute for a URL.
Unset an attribute
Built-in and custom attributes can be unset, that is, turned off, with a leading or trailing bang symbol (!) added to its name in an attribute entry.
= Page Title
:!sectanchors:
:table-caption!:Once unset, an attribute’s behavior and value are no longer available to the page.
Precedence rules
Attributes can be scoped to a whole site by declaring them in a site’s playbook file. You can apply attributes to a single component version by declaring them in a component descriptor file (i.e., antora.yml). Attributes which are hard set or hard unset in the playbook or component descriptor take precedence over attributes defined in a page. This precendence order can be inverted using the precedence modifier.
Intrinsic attributes can never be modified and are thus considered read-only.
See the precedence rules for site attributes and component version attributes for more information.