Define and Modify Attributes

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.

Example 1. Set a built-in attribute
= 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.

The name cannot contain dots (.) or blank spaces.

Although uppercase characters are permitted in an attribute name, the name is 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.

Example 2. Define a custom attribute using an attribute entry
= Page Title
:url-repo: https://gitlab.com/antora/demo/docs-site

Now, 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.