Escape and Prevent Substitutions

The AsciiDoc syntax offers several approaches for preventing substitutions from being applied.

Escape with backslashes

To prevent a punctuation character from being interpreted as an attribute reference or formatting syntax (e.g., _, ^) in normal content, prepend the character with a backslash (\).

Example 1. Prevent unintended substitutions with a backslash in normal content
In /items/\{id}, the id attribute isn't replaced.
The curly braces around it are preserved.

\*Stars* isn't displayed as bold text.
The asterisks around it are preserved.

\§ appears as an entity reference.
It's not converted into the section symbol (§).

\=> The backslash prevents the equals sign followed by a greater
than sign from combining to form a double arrow character (=>).

\[[Word]] is not interpreted as an anchor.
The double brackets around it are preserved.

[\[[Word]]] is not interpreted as a bibliography anchor.
The triple brackets around it are preserved.

The URL \https://example.org isn't converted into an active link.

The backslash can also prevent character replacements, macros, and attribute replacements. The results of Example 1 are below.

In /items/{id}, the id attribute isn’t replaced. The curly braces around it are preserved.

*Stars* isn’t displayed as bold text. The asterisks around it are preserved.

§ appears as an entity reference. It’s not converted into the section symbol (§).

=> The backslash prevents the equals sign followed by a greater than sign from combining to form a double arrow character (⇒).

[[Word]] is not interpreted as an anchor. The double brackets around it are preserved.

[[[Word]]] is not interpreted as a bibliography anchor. The triple brackets around it are preserved.

The URL https://example.org isn’t converted into an active link.

Notice that the backslash is removed so it doesn’t display in your output.

To prevent two adjacent characters (e.g., __, ##), from being interpreted as AsciiDoc syntax you need to precede it with two backslashes (\\).

Example 2. Prevent unintended substitutions with two backslashes in normal content
The text \\__func__ will appear with two underscores
in front of it and after it.
It won't be italicized.

The results of Example 2 are below.

The text __func__ will appear with two underscores in front of it and after it. It won’t be italicized.

Passthroughs

A passthrough is the primary mechanism by which to escape content in AsciiDoc. They’re far more comprehensive and consistent than using a backslash. As the name implies, a passthrough passes content directly through to the output document without applying any substitutions.

You can control and prevent substitutions in inline text with the inline passthrough macros and for entire blocks of content with the block passthrough.

The inline + passthrough takes precedence over all other inline formatting. Therefore, if you need to output a literal plus when it would otherwise match a passthrough, you have two options.

First, you can escape it using the {plus} attribute reference:

`{plus}` and `{plus}`

Alternately, you can escape the pair using a backslash.

`\+` and `+`

The backslash is only required before the pair, not before each occurance of the plus.