Positional and Named Attributes

Let’s break down the difference between positional and named attributes.

Positional attribute

Values placed in a specific order in an attribute list don’t require an attribute name. The attribute that the value is assigned to depends on the type of the element. Here are some examples:

  • icon: (1) size

  • image: and image:: (1) alt text, (2) width, (3) height

  • Delimited blocks: (1) block name (aka style)

  • Other inline quoted text: (1) role and ID shorthand

  • link: and xref: (1) link text

  • Custom blocks and macros can specify positional attributes

For example, the following two image macros are equivalent.

image::sunset.jpg[Sunset,300,400]

image::sunset.jpg[alt=Sunset,width=300,height=400]

The second macro is just a duplicate of the first macro written out longhand.

Named attribute

A named attribute consists of a name and a value separated by an = character (e.g., name=value).

If the value contains a space, comma, or quote character, it must be enclosed in double or single quotes (e.g., name="value with space"). In all other cases, the surrounding quotes are optional. If present, the enclosing quotes are dropped from the parsed value.

If the value contains the same quote character used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., value="the song \"Dark Horse\"").

Unset a named attribute

To undefine a named attribute, set the value to None (case sensitive).

Substitutions

Attribute references are expanded before the block attribute list is processed. Therefore, it’s not necessary to force substitutions to be applied if you simply want to use a document attribute reference in a block attribute.

If the attribute name (for a positional attribute) or value (for a named attribute) is enclosed in single quotes (e.g., title='Processed by https://asciidoctor.org'), normal substitutions are applied to the value at assignment time (with some exceptions). This is also true for positional attributes, such as the attribution for a quote block. No special processing is performed, except for attribute reference expansion, if the value is not enclosed in quotes or is enclosed in double quotes.

If the value contains the same quote character used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., title='A \'use case\' diagram, generated by https://plantuml.com').

Attribute list parsing

The exact rules for determining whether an attribute is positional, and what defines the boundaries of an individual attribute, are defined below.

A name consists of a word character (letter or numeral) followed by any number of word characters, . charactes, or - characters, followed by something else (including the end of the string)

  • Parsing an attribute proceeds from the beginning of the attribute list string or after a previously recognized delimiter (,).

  • Blank space is skipped.

  • If a valid attribute name is found, and it is followed by an equals sign (=), then the parser recognizes this as a named attribute. The text after the equals sign (=) and up to the next comma or end of list is taken as the attribute value. Spaces around the equals sign (=) are ignored.

  • Otherwise this is a positional attribute with value starting after the skipped blank space and ending before (optional) blank space preceding the next delimiter (,).

  • To parse the attribute value:

    • If the first character is not a quote, the string is read until the next delimiter or end of string.

    • If the first character is ", then the string is read until the next unescaped quote or, if there is no closing quote, the next delimiter. If there is a closing quote, the quotes are removed; if not, the initial quote is retained.

    • If the next character is ' then the string is read until the next unescaped ', or if there is no closing ', the next delimiter. If there is a closing ', the enclosing ' characters are removed; if not, the initial ' is retained. If there is a closing ' and the first character is not an escaped ' substitutions are performed as described above.