Substitutions

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:

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.