Literal Monospace

Unlike other markup languages, monospaced text in AsciiDoc is not synonymous with literal text. Instead, it gets interpreted just like normal text. In other words, it’s subject to all text substitutions by default.

This might be surprising at first. But there’s good reason for this difference. In AsciiDoc, you can take advantage of attribute references and inline macros inside of a monospaced text span. The drawback, of course, is that you have to be careful to escape these special characters if you intend to output them without special formatting (i.e., as literal text).

One way to prevent the processor from interpreting special characters in monospaced text is to escape them using backslash characters, just as you would with normal text. However, escaping individual occurrences that way can be tedious. That’s why AsciiDoc offers a special type of monospace formatting called the literal monospace.

To make a true literal codespan in AsciiDoc, you must enclose the monospaced text in a passthrough. Rather than using a single pair of backtick characters, you’ll use the combination of the backtick and plus characters, where the plus characters fall on the inside of the backtick characters (e.g., `+text+`). The plus characters are a shorthand for the pass:c[] enclosure.

Example 1 contains literal, monospaced text.

Example 1. Literal monospace syntax
You can reference the value of a document attribute using
the syntax `+{name}+`, where `name` is the attribute name.

This shorthand syntax can accommodate most of the literal monospace cases. The main exception is when the text itself contains plus characters. To avoid confusing the processor, you’ll need to switch to using the more formal passthrough macro to handle these cases.

Example 2 shows literal, monospaced text that contains plus characters.

Example 2. Literal monospace syntax with + characters
`pass:[++]` is the increment operator in C.

Passthroughs are a general purpose utility in AsciiDoc. You can learn about the various passthrough options in Inline Passthroughs.