How to prevent URLs containing formatting characters from getting mangled

If a URL that contains AsciiDoc formatting characters (such as ~, $$ and such) appears in span of paragraph text, it’s likely going to get mangled. This happens because of the order in which the AsciiDoc processor applies substitutions. Suffice to say, it’s nearly impossible for AsciiDoc to know not to interpret the formatting characters in these URLs.

However, AsciiDoc does provide mechanisms to prevent URLs like this from getting managed. Two solutions are presented here.

Approach 1: Attributes

The best way to handle wacky URLs, and URLs in general, is to define them in attributes in the header of the document, then use the attribute reference in the body of the document in place of the URL.

 = Document Title
 Author Name
 :artifacts-nexus-url: https://repository.jboss.org/nexus/#nexus-search;gav~org.hibernate~hibernate-search-modules~~~

 {artifacts-nexus-url}[Hibernate Search Modules]

Attribute values do not receive substitutions (unless wrapped in an inline macro), so it’s safe to shove any crazy characters in there.

Approach 2: Inline pass macros

The other way to prevent characters in a URL from being interpreted is by wrapping the link definition in an inline pass (passthrough) macro.

 pass:macros[https://repository.jboss.org/nexus/#nexus-search;gav~org.hibernate~hibernate-search-modules~~~[Hibernate Search Modules\]]

The inline pass macro allows you to escape text, then apply substitutions to it when it is inserted back into the document. The link substitution is a macro, so here we enable the macros substitution to convert the text into a link.

The \] is required to prevent the inline pass macro from ending prematurely. It is unescaped when the text is stored.

Note	The inline pass macro is similar to the double dollar ($$) escape, except that the inline pass macro gives you to opportunity to perform substitutions on the text prior to reinsertion into the document.

Caution

This solution works in Asciidoctor, but is known to be error prone in AsciiDoc (Python).