Element Attributes

Element attributes are a powerful means of controlling the built-in settings of individual block and inline elements in the AsciiDoc syntax. They can also be used to add supplemental information, such as citation metadata and fallback content, to certain elements.

What are element attributes?

Element attributes define the built-in and user-defined settings and metadata that can be applied to an individual block element or inline element in a document (including macros). Although the include directive is not technically an element, element attributes can also be defined on an include directive.

Element attributes may be positional (value only) or named (key/value pair). Some built-in and extension elements will map a positional attribute to a named attribute. Each element recognizes a predefined set of positional and/or named element attributes. Authors may define any number of custom element attributes for passing information to an extension or document analyzer.

Like document attributes, there’s no strict schema for element attributes, or for the value of the options element attribute. There’s a core set of reserved attributes shared by all block elements and most inline elements, which includes id, role, opts, and title. Certain elements may reserve additional attributes and option values. For example, the source block reserves the lang attribute to set the source language and the linenums option to enable line numbers. The link macro reserves the window attribute to change the target window of a link and the nofollow option to prevent crawlers from following it. Otherwise, the schema for element attributes is open-ended, thus allowing extensions to use them for their own purpose.

Element attributes are commonly used for the following purposes:

  • Declare the ID of an element

  • Turn on or turn off an individual element’s built-in features

  • Configure the built-in features of an individual element

  • Apply user-defined information, such as citation metadata, fallback text, link text, and target content, to an individual element

  • Apply user-defined roles and behaviors to an individual element

Unlike document attributes, element attributes are defined directly on the element to which they apply using an attribute list.

Attribute lists

Attributes are assigned to block and inline elements using an attribute list. For block elements, the attribute list is placed in a block attribute lines above the block. For block and inline macros, the attribute list is placed between the square brackets of the macro. For formatted text, the attribute list is placed in the square brackets in front of the text enclosure. However, formatted text only supports a specialized form of the attribute list.

Attribute lists:

Example 1. Anatomy of an attribute list
[positional_attribute_1,positional_attribute_2,named_attribute="value"]

Entries in an attribute list are separated by commas, excluding commas inside a quoted value. The syntax used for an entry in the attribute list determines whether it’s a positional or named attribute.

As mentioned in the previous setting, the schema for element attributes is open-ended. Any positional or named attributes that are not recognized will be stored on the element, but will not have an impact on the behavior or output. Extensions may use this auxiliary information to influence their behavior and/or customize the output.