Substitutions and Passthroughs

Substitutions

Text substitution elements replace characters, markup, attribute references, and macros with converter specific styles and values. When Asciidoctor processes a document it uses a set of six text substitution elements. The processor runs the text substitution elements in the following order.

In turn, these substitutions are organized into composite value groups. The table below shows which substitution elements are included in each group.

Substitution groups
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

By default, the normal substitution group is applied to most block and inline elements. However, there are a few exceptions.

The header substitution group is applied to metadata lines (author and revision information) in the document header. This group is also applied to the values of attribute entries, regardless of whether those entries are defined in the header or elsewhere in the document. In the header, only special characters and attribute references are replaced. In attribute entries, you can also use the inline pass macro.

Fenced, literal, listing, and source blocks are processed with the verbatim substitution group. Only special characters are replaced in these blocks.

The pass substitution group can only be applied to passthrough elements. Attribute references and macros are replaced in passthroughs.

The none substitution group is applied to comment blocks.

The title substitution group

The title substitution group includes the same text substitutions as the normal group. However, the order that the substitutions are executed is slightly different. Text substitutions are applied to titles in the following sequence:

  1. Special characters

  2. Quotes

  3. Replacements

  4. Inline macros

  5. Attribute references

  6. Post replacements

Passthroughs and Escapes

Asciidoctor provides several approaches for preventing substitutions depending on the situation. When you want to prevent punctuation from being interpreted as formatting markup, escaping the punctuation with a backslash may be sufficient. For more comprehensive escape and substitution control, you can use a passthrough.

The passthrough is the primary mechanism by which to escape content in AsciiDoc. As the name implies, a passthrough passes content directly through to the output document. In some forms, it’s possible to apply a custom set of substitutions before the content is reintroduced. Otherwise, the content is excluded from all substitutions. AsciiDoc provides a number of inline passthrough mechanisms and a passthrough block.