URLs and Links

A Uniform Resource Link (URL) represents the location of a resource on the web. Typical URLs contain a scheme, domain name, file name, and extension.

move image

Asciidoctor recognizes the following common schemes without the help of any markup.

  • http

  • https

  • ftp

  • irc

  • mailto

  • email@email.com

You can think of these like implicit macro names. Since the URL in the example below begins with a protocol (in this case https followed by a colon), Asciidoctor will automatically turn it into a hyperlink when it is processed.

The homepage for the Asciidoctor Project is https://www.asciidoctor.org. (1)
1 The trailing period will not get caught up in the link.

To prevent automatic linking of an URL, prepend it with a backslash (\).

Hide URI schemes

If you prefer URLs to be shown without a visible scheme, set the hide-uri-scheme attribute in the document’s header.

:hide-uri-scheme:

https://asciidoctor.org

When the hide-uri-scheme attribute is set, the above URL will render as follows:

<a href="https://asciidoctor.org">asciidoctor.org</a>

Note the absence of https in the contents of the <a> element.

To attach a URL to text, enclose the text in square brackets at the end of the URL.

Chat with other Asciidoctor users in the irc://irc.freenode.org/#asciidoctor[Asciidoctor IRC channel].

Additionally, you can format the linked text.

Ask questions on the http://discuss.asciidoctor.org/[*mailing list*].
Rendered URLs

The homepage for the Asciidoctor Project is asciidoctor.org.

Chat with other Asciidoctor users in the Asciidoctor IRC channel.

Ask questions on the mailing list.

When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the link macro. The link macro is a stronger version of a URI macro, which you can think of like an unconstrained macro. The URL is preceded by link: and followed by square brackets. The square brackets may include optional link text. The URL is used for the text of the link if link text is not specified. If the linkattrs document attribute is set, the square brackets also accepts attributes, which allows a window name or role to be specified.

Anatomy of a link macro
link:url[optional link text, optional target attribute, optional role attribute]

Let’s consider a case where we need to use the link macro (instead of just a URI macro) to expand a link when it’s not adjacent to a word boundary (i.e., unconstrained).

search/link:https://ecosia.org[Ecosia]

search/Ecosia

If we didn’t use the link: prefix in this case, the URL macro would not be detected by the parser.

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. Asciidoctor plans to handle URLs more carefully in the future (see issue #281), which may be solved by moving to a grammar-based parser (see 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}.

Asciidoctor won’t break links with underscores when they are assigned to an attribute because quotes,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 subs-mac,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 ++ around the URL only. However, when you use this approach, Asciidoctor 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 issue #625.

Next, we’ll add a target and role to a link macro.

Remember, when you use attributes in the link macro, you must also set the linkattrs document attribute in the header. Asciidoctor does not parse attributes in the link macro by default. Once you’ve activated the linkattrs attribute, you can then specify the name of the target window using the window attribute.

= Asciidoctor Document Title
:linkattrs:

Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage, window="_blank"].

Let’s view the raw HTML of the Asciidoctor homepage.

Since _blank is the most common window name, we’ve introduced shorthand for it. Just end the link text with a caret (^):

Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage^].
If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence with a backslash.

When the linkattrs attribute is set, you can add a role (i.e., CSS class) to the link.

Chat with other Asciidoctor users in the irc://irc.freenode.org/#asciidoctor[Asciidoctor IRC channel] or on the http://discuss.asciidoctor.org/[*mailing list*^, role="green"].

Chat with other Asciidoctor users in the Asciidoctor IRC channel or on the mailing list.

Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. When they’re enabled, you must surround the link text in double quotes if it contains a comma.