Attribute Entry Substitutions

The AsciiDoc processor automatically applies substitutions from the header substitution group to the value of an attribute entry prior to the assignment, regardless of where the attribute entry is declared in the document. The header substitution group, which replaces special characters followed by attribute references, is applied to the values of attribute entries, regardless of whether the entries are defined in the header or in the document body. This is the same group that gets applied to metadata lines (author and revision information) in the document header.

That means that any inline formatting in an attribute value isn’t interpreted because:

  1. inline formatting is not applied when the AsciiDoc processor sets an attribute, and

  2. inline formatting is not applied when an attribute is referenced since the relevant substitutions come before attributes are resolved.

Change substitutions when assigning a value

If you want the value of an attribute entry to be used as is (not subject to substitutions), or you want to alter the substitutions that are applied, you can enclose the value in the inline pass macro (i.e., pass:[]). The inline pass macro accepts a list of zero or more substitutions in the target slot, which can be used to control which substitutions are applied to the value. If no substitutions are specified, no substitutions will be applied.

In order for the inline macro to work in this context, it must completely surround the attribute value. If it’s used anywhere else in the value, it will be ignored.

Here’s how to prevent substitutions from being applied to the value of an attribute entry:

:cols: pass:[.>2,.>4]

This might be useful if you’re referencing the attribute in a place that depends on the unaltered text, such as the value of the cols attribute on a table.

Here’s how we can apply the quotes substitution to the value of an attribute entry:

:app-name: pass:quotes[MyApp^2^]

Internally, the value is stored as MyApp<sup>2</sup>. You can inspect the value stored in an attribute using this trick:


You can also specify the substitution using the single-character alias, q.

:app-name: pass:q[MyApp^2^]

The inline pass macro kind of works like an attribute value preprocessor. If the processor detects that an inline pass macro completely surrounds the attribute value, it:

  1. reads the list of substitutions from the target slot of the macro

  2. unwraps the value from the macro

  3. applies the substitutions to the value

If the macro is absent, the value is processed with the header substitution group.

Substitutions for attributes defined outside the document

Unlike attribute entries, substitutions are not applied to the value of an attribute passed in to the AsciiDoc processor. An attribute can be passed into the AsciiDoc processor using the -a CLI option or the :attributes API option. When attributes are defined external to the document, the value must be prepared so it’s ready to be referenced as is. If the value contains XML special characters, that means those characters must be pre-escaped. The exception would be if you intend for XML/HTML tags in the value to be preserved. If the value needs to reference other attributes, those values must be pre-replaced.

Let’s consider the case when the value of an attribute defined external to the document contains an ampersand. In order to reference this attribute safely in the AsciiDoc document, the ampersand must be escaped:

$ asciidoctor -a equipment="a bat &amp; ball" document.adoc

You can reference the attribute as follows:

To play, you'll need {equipment}.

If the attribute were to be defined in the document, this escaping would not be necessary.

:equipment: a bat & ball

That’s because, in contrast, substitutions are applied to the value of an attribute entry.

Change substitutions when referencing an attribute

You can also change the substitutions that are applied to an attribute at the time it is resolved. This is done by manipulating the substitutions applied to the text where it is referenced. For example, here’s how we could get the processor to apply quote substitutions to the value of an attribute:

:app-name: MyApp^2^

The application is called {app-name}.

Notice that we’ve swapped the order of the attributes and quotes substitutions. This strategy is akin to post-processing the attribute value.