40. Passthroughs

The passthrough is the primary mechanism by which to escape content in AsciiDoc (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. When using the passthrough block or macro, it’s possible to specify a custom set of substitutions to be applied before the content is reintroduced. Other forms of passthroughs, such as the single and double plus, apply substitutions strictly for compliance with the output format.

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.

40.1. Passthrough Macros

Asciidoctor supports several forms of the passthrough macro.

inline 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}>__]
single and double plus

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

triple plus

A special syntax for designating passthrough content. Does not apply any substitutions (equivalent to the inline pass macro) and doesn’t support explicit substitutions.

double dollar (deprecated)

A deprecated special syntax for designating passthrough content. Like the triple plus, does not apply any substitutions and doesn’t support explicit substitutions.

Asciidoctor does not implement the block pass macro. Instead, you should use a pass block.

40.1.1. Inline pass macro and explicit substitutions

To exclude a phrase 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.

40.1.2. Triple plus passthrough

The triple-plus passthrough works much the same way as the pass macro. To exclude content from substitutions, enclose it in triple pluses (+++).

+++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.

40.1.3. Nesting blocks and passthrough macros

When you’re using passthroughs inside literal and listing blocks, it can be easy to forget that the triple-plus, double-dollar, and backtick passthroughs are macros (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();

40.2. Passthrough Blocks

The passthrough block and pass block style exclude block content from all substitutions (unless specified otherwise).

A passthrough block is delimited by four plus signs (++++). The pass style is implied.

++++
<video poster="images/movie-reel.png">
  <source src="videos/writing-zen.webm" type="video/webm">
</video>
++++

(Keep in mind that AsciiDoc has a video macro, so this example is merely for demonstration. However, a passthrough could come in handy if you need to output more sophisticated markup than what the built-in HTML converter produces).

The pass style can also be set on a paragraph or an open block.

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

You can use the subs attribute to specify a comma-separated list of substitutions. These substitutions will be applied to the content prior to it being reintroduced to the output document.

[subs=attributes]
++++
{name}
image:tiger.png[]
++++

The content of the pass block does not get wrapped in a paragraph. Therefore, you can use the pass style in combination with the normal substitution category to output content without generating a paragraph.

[subs=normal]
++++
Normal content which is not enclosed in a paragraph.
++++