Inline Passthroughs

AsciiDoc supports several inline passthrough macros.

Inline passthrough macros

single and double plus

A special syntax for preventing inline text from being formatted. Only special characters are replaced in the output format. The substitutions can’t be modified for this type of passthrough.

triple plus

A special inline syntax for designating passthrough content. No substitutions are applied nor can they be added using the step and group substitution values.

inline pass macro

An inline macro named pass that can be used to passthrough content. You can apply specific substitutions to the macro’s target using substitution types and groups.

pass:[content like #{variable} passed directly to the output] followed by normal content.

content with only select substitutions applied: pass:c,a[__<{email}>__]

When you need to prevent or control the substitutions on one or more blocks of content, use a delimited passthrough block or the pass block style.

Single and double plus

The single and double plus passthroughs prevent text enclosed in either a pair of single pluses (+) or a pair of double pluses (++) from being formatted.

A +word+, a +sequence of words+, or ++char++acters that are escaped from formatting.

The single and double pluses represent the constrained and unconstrained passthrough, respectively. They have boundaries that match the constrained and unconstrained formatting marks. The main difference, however, is that they are applied first to suppress formatting.

This type of passthrough is intended to suppress any special meaning of the source text itself. This passthrough type still ensures, however, that the content is properly escaped in the output. That means the special characters substitution is still applied.

As with all constrained pairs, the single plus passthrough is designed to be used around a word or phrase.

A word or phrase between single pluses, such as +/document/{id}+, is not substituted.
However, the special characters +<+ and +>+ are still escaped in the output.

You can also escape formatting marks, like +``+.

Being an unconstrained pair, the double plus passthrough can be used anywhere in the text.

Text formatting is not applied to a link target if it is surrounded by double pluses.
For example, link:++https://example.org/now_this__link_works.html++[].

You can also escape formatting marks, like all-natural++*++.

An attribute reference within a word, such as dev++{conf}++, is not replaced.

The single and plus passthroughs are a surefire alternative to backslash escaping.

Note that the single and plus passthroughs only prevent substitutions. They do not format the text in monospace. If you want to do both, you must enclose the pair in a monospace formatting pair, known as literal monospace.

Triple plus

The triple plus passthrough excludes content enclosed in a pair of triple pluses (+++) from all substitutions.

+++content passed directly to the output+++ followed by normal content.

The triple plus macro is often used to output custom HTML or XML.

The text +++<u>underline me</u>+++ is underlined.

The text underline me is underlined.

Inline pass macro

Like other inline passthroughs, the inline pass macro can be used to control the substitutions applied to a run of text. To exclude inline content from all of the substitutions, enclose it in the inline pass macro.

Here’s one way to format text as underline when generating HTML from AsciiDoc:

The text pass:[<u>underline me</u>] is underlined.

And here’s the result.

The text underline me is underlined.

Using passthroughs to send content directly to the output can couple your content to a specific output format, such as HTML. To avoid this risk, you should consider using conditional preprocessor directives to select content for different output formats based on the current backend.

What sets the inline pass macro apart from the alternatives is that it allows the substitutions to be customized. The inline pass macro also plays a critical role in the document header. In fact, it’s the only macro that is processed in the document header by default as part of the header substitution group (though it can be used to enable other substitutions, as demonstrated in this section).

Let’s look at how to use the inline pass macro to hand select substitutions.

Custom substitutions

You can customize the substitutions applied to the content of an inline pass macro by specifying one or more substitution values in the target of the macro. Multiple values must be separated by commas and may not contain any spaces. The substitution value is either the formal name of a substitution type or group, or its shorthand.

The following table lists the allowable substitution values:

Substitution values accepted by the inline pass macro
Shorthand	Substitution Type
`c`	`specialchars`
`a`	`attributes`
`r`	`replacements`
`m`	`macros`
`p`	`post replacements`
Shorthand	Substitution Group
`n`	`normal`
`v`	`verbatim`

For example, the quotes substitution (i.e., q or quotes) is enabled on the inline passthrough macro as follows:

The text pass:q[<u>underline *me*</u>] is underlined.

Here’s the result.

The text underline me is underlined.

To enable multiple substitution groups, separate each value in the macro target by a comma:

The text pass:q,a[<u>underline _{docname}_</u>] is underlined.

Here’s the result.

The text underline pass-macro is underlined.

Nesting blocks and passthroughs

When you’re using passthroughs inside literal and listing blocks, it can be easy to forget that the single plus and triple plus passthroughs are macros substitutions. To enable the passthroughs, assign the macros value to the subs attribute.

[source,java,subs="+quotes,+macros"]
----
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            **.antMatchers("/resources/+++**+++").permitAll()**
            .anyRequest().authenticated()
            .and()
        .formLogin()
            .loginPage("/login")
            .permitAll();
----

To learn more about applying substitutions to blocks, see Customize the Substitutions Applied to Blocks.

protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            .antMatchers("/resources/**").permitAll()
            .anyRequest().authenticated()
            .and()
        .formLogin()
            .loginPage("/login")
            .permitAll();