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.

Triple plus macro

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();