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:

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

Attributes can be assigned to block and inline elements using an attribute list (often abbreviated as attrlist).

Entries in an attribute list are separated by commas, excluding commas inside quotes. The syntax used for an attribute list entry determines whether it’s a positional or named attribute. The space after the comma separating entries is optional. To learn more about how the attribute list is parsed, see Positional and Named Attributes.

For block elements, the attribute list is placed inside one or more block attribute lines. A block attribute line is any line of text above the start of a block (e.g., the opening delimiter or simple content) that begins with [ and ends with ]. This line can be interspersed with other block metadata lines, such as the block title. The text enclosed in the [ and ] boundaries is assumed to be a valid attribute list and the line is automatically consumed. If the text cannot be parsed, an error message will be emitted to the log.

For block and inline macros, the attribute list is placed between the square brackets of the macro. The text in an attribute list of a block macro never needs to be escaped. For an inline macro, it may be necessary to escape the text in the attribute list to avoid prematurely ending the macro or unwanted substitutions.

For formatted text, the attribute list is placed in the square brackets in front of the text enclosure. However, formatted text only supports a restricted form of the attribute list. Specifically, it does not support named attributes, only the attribute shorthand syntax.

Attribute lists:

As mentioned in the previous section, 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.