Substitutions

Substitutions are applied to leaf content of a block. Substitutions determine how the text is interpreted. If no substitutions are applied, the text is passed to the converter as entered. Otherwise, the substitutions transform that text.

Substitutions replace references, formatting marks, characters and character sequences, and macros. Substitutions are organized into types and those types are bundled into groups. This page provides an overview of these classifications. Subsequence pages go into detail about each substitution type.

Substitution types

Each substitution type replace characters, markup, attribute references, and macros in text with the appropriate output for a given converter. When a document is processed, up to six substitution types may be carried out depending on the block or inline element’s assigned substitution group. The processor runs the substitutions in the following order:

Special Character Substitutions
Quotes Substitutions (i.e., inline formatting)
Attribute References Substitution
Character Replacement Substitutions
Macro Substitutions
Post Replacement Substitutions

For convenience, these types are grouped and ordered into substitution groups.

Substitution groups

Each block and inline element has a default substitution group that is applied unless you customize the substitutions for a particular element. Table 1 shows the substitution types that are executed in each group.

Table 1. Substitution types used by each substitution group
Group	Special characters	Quotes	Attributes	Replacements	Macros	Post replacements
Header	Yes	No	Yes	No	No	No
None	No	No	No	No	No	No
Normal	Yes	Yes	Yes	Yes	Yes	Yes
Pass	No	No	No	No	No	No
Verbatim	Yes	No	No	No	No	No

Normal substitution group

The normal substitution group (normal) is applied to the majority of the AsciiDoc block and inline elements except for those specific elements listed under the groups described in the next sections.

Header substitution group

The header substitution group (header) is applied to metadata lines (author and revision information) in the document header. It’s also applied to the values of attribute entries, regardless of whether those entries are defined in the document header or body. Only special characters, attribute references, and the inline pass macro are replaced in elements that fall under the header group.

You can use the inline pass macro in attribute entries to customize the substitution types applied to the attribute’s value.

Verbatim substitution group

Literal, listing, and source blocks are processed using the verbatim substitution group (verbatim). Only special characters are replaced in these blocks.

Pass substitution group

No substitutions are applied to three of the elements in the pass substitution group (pass). These elements include the passthrough block, inline pass macro, and triple plus macro.

The inline single plus and double plus macros also belong to the pass group. Only the special characters substitution is applied to these elements.

None substitution group

The none substitution group (none) is applied to comment blocks. No substitutions are applied to comments.

Escaping substitutions

The AsciiDoc syntax offers several approaches for preventing substitutions from being applied. When you want to prevent punctuation and symbols from being interpreted as formatting markup, escaping the punctuation with a backslash may be sufficient. For more comprehensive substitution prevention and control, you can use inline passthrough macros or passthrough blocks.