Asciidoctor User Manual

26. URLs

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.

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 (the bare email address being a special case). 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://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 (\).

Once launched, the site will be available at \https://example.org.

If you prefer URLs to be shown with the scheme hidden, 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 inside the <a> element.

To attach a URL to text, enclose the text in square brackets at the end of the URL, thus making it an URL macro:

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

Additionally, you can format the linked text.

Ask questions on the https://discuss.asciidoctor.org/[*mailing list*].

Rendered URLs

The homepage for the Asciidoctor Project is https://asciidoctor.org.

Chat with other Fedora users in the Fedora IRC channel.

Ask questions on the mailing list.

You may also want to append empty square brackets to force the URL to be parsed when it would not normally be recognized, such as if it’s enclosed in double quotes:

Type "https://asciidoctor.org[]" into the location bar of your browser.

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. Prior to 1.5.7, if the linkattrs document attribute is set, the text in square brackets is parsed as attributes, which allows a window name or role to be specified. Since 1.5.7, attributes are parsed automatically if an equal sign is found after a comma (e.g., [link text,window=_blank]).

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

Prior to 1.5.7, Asciidoctor does not parse attributes in the link macro by default. If you want attributes in the link macro to be parsed, you must set the linkattrs document attribute in the header. Since 1.5.7, this parsing is automatic (and the attribute is not required) if an equal sign is found after a comma. When attribute parsing is enabled, you can then specify the name of the target window using the window attribute.

= Asciidoctor Document Title

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 attribute parsing is enabled, you can add a role (i.e., CSS class) to the link.

Chat with other Asciidoctor users on the https://discuss.asciidoctor.org/[*mailing list*^,role=green].

Chat with other Asciidoctor users 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.

26.1. Link to Relative Files

If you want to link to an external file relative to the current document, use the link macro in front of the file name.

link:protocol.json[Open the JSON file]

If your file is an HTML file, you can link directly to a section in the document, append a hash (#) followed by the section’s ID to the end of the file name.

link:external.html#livereload[LiveReload]

26.2. Summary

Link attributes and values
Attribute	Value(s)	Example Syntax	Comments
linkattrs		`:linkattrs:`	Must be set in the header to parse link macro attributes prior to 1.5.7. Since 1.5.7, attributes are parsed automatically if an equal sign is found after a comma (e.g., `[link text,window=_blank]`).
window	blank	https://discuss.asciidoctor.org[Discuss Asciidoctor,window=_blank]	The blank window target can also be specified using `^` at the end of the link text.
window	^	http://example.org["Google, Yahoo, Bing^"] and https://discuss.asciidoctor.org[Discuss Asciidoctor^]
role	CSS classes available to inline elements	https://discuss.asciidoctor.org[Discuss Asciidoctor,role=teal]
id	name of element, custom link text	<<section-title,cross reference text>>	Applies to cross references