Troubleshooting Complex URLs

A URL may not display correctly when it contains characters such as underscores (_) or carets (^). This problem occurs because the markup parser interprets parts of the URL (i.e., the link target) as valid text formatting markup. Most lightweight markup languages have this issue because they don’t use a grammar-based parser. The AsciiDoc language plans to handle URLs more carefully in the future (see Asciidoctor issue #281), which may be solved by moving to a grammar-based parser (see Asciidoctor issue #61). Thankfully, there are many ways to include URLs of arbitrary complexity using the AsciiDoc passthrough mechanisms.

Solution A

The simplest way to get a link to behave is to assign it to an attribute.

= Document Title
:link-with-underscores: https://asciidoctor.org/now_this__link_works.html

This URL has repeating underscores {link-with-underscores}.

The AsciiDoc processor won’t break links with underscores when they are assigned to an attribute because inline formatting markup is substituted before attributes. The URL remains hidden while the rest of the document is being formatted (strong, emphasis, monospace, etc.).

Solution B

Another way to solve formatting glitches is to explicitly specify the formatting you want to have applied to a span of text. This can be done by using the inline pass macro. If you want to display a URL, and have it preserved, put it inside the pass macro and enable the macros substitution, which is what substitutes links.

This URL has repeating underscores pass:macros[https://asciidoctor.org/now_this__link_works.html].

The pass macro removes the URL from the document, applies the macros substitution to the URL, and then restores the processed URL to its original location once the substitutions are complete on the whole document.

Alternatively, you can use the double plus inline macro (++) around the URL only. However, when you use this approach, the AsciiDoc processor won’t recognize it as a URL any more, so you have to use the explicit link prefix.

This URL has repeating underscores link:++https://asciidoctor.org/now_this__link_works.html++[].

For more information, see Asciidoctor issue #625.