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 (\).
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 (\\).
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.