Inline Passthroughs

Asciidoctor supports several forms of the passthrough macro.

Inline passthrough macros

single plus

A special syntax for preventing text from being formatted. Only escapes special characters and doesn’t support explicit substitutions.

triple plus

A special syntax for designating passthrough content. Does not apply any substitutions and doesn’t support explicit substitutions.

pass macro

An inline macro named pass that can be used to passthrough content. Supports an optional set of substitutions.

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 set 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 and explicit substitutions

To exclude inline content from substitutions and disable escaping of special characters, enclose it in the inline pass macro. For example, here’s one way to format text as underline when generating HTML from AsciiDoc:

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

The text underline me is underlined.

If you want to enable ad-hoc quotes substitution, then assign the macros value to subs and use the inline pass macro.

[subs=+macros] (1)
----
I better not contain *bold* or _italic_ text.
pass:quotes[But I should contain *bold* text.] (2)
----
1 macros is assigned to subs, which allows any macros within the block to be processed.
2 The pass macro is assigned the quotes value. Text within the square brackets will be formatted.

The inline pass macro does introduce additional markup into the source code that could make it invalid in raw form. However, the output it produces will be valid when viewed in a viewer (HTML, PDF, etc.).

I better not contain *bold* or _italic_ text.
But I should contain bold text.

The inline pass macro also accepts shorthand values for specifying substitutions.

  • c = special characters

  • q = quotes

  • a = attributes

  • r = replacements

  • m = macros

  • p = post replacements

For example, the quotes text substitution value is assigned in the inline passthrough macro below:

The text pass:q[<u>underline *me*</u>] is underlined and the word "`me`" is bold.

The text underline me is underlined and the word “me” is bold.

Using passthroughs to pass content (without substitutions) can couple your content to a specific output format, such as HTML. In these cases, you should use conditional preprocessor directives to route passthrough content for different output formats based on the current backend.

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 (not quotes). If you want to enable the passthroughs, make sure to 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();
----
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            .antMatchers("/resources/**").permitAll()
            .anyRequest().authenticated()
            .and()
        .formLogin()
            .loginPage("/login")
            .permitAll();