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.
Asciidoctor recognizes the following common schemes without the help of any markup.
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 (
If you prefer URLs to be shown without a visible scheme, set the
hide-uri-scheme attribute in the document’s header.
When the hide-uri-scheme attribute is set, the above URL will render as follows:
Note the absence of https in the contents of the
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*].
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 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.
linkattrs document attribute is set, the square brackets also accepts attributes, which allows a window name or role to be specified.
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).
If we didn’t use the
link: prefix in this case, the URL macro would not be detected by the parser.
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
= Asciidoctor Document Title :linkattrs: Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage, window="_blank"].
_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.|
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"].
|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.|