Link Macro
The link macro is the most explicit method of making a link in AsciiDoc. It’s only necessary when the behavior of autolinks and URL macros proves insufficient. This page covers the anatomy of the link macro, when it’s required, and how to use it.
Anatomy
The link macro is an inline macro. Like other inline macros, its syntax follows the familiar pattern of the macro name and target separated by a colon followed by an attribute list enclosed in square brackets.
link:<target>[<attrlist>]The <target> becomes the target of the link.
the <attrlist> is the link text unless a named attribute is detected.
See link macro attribute list to learn how the <attrlist> is parsed.
Like all inline macros, the link macro can be escaped using a leading backslash (\).
Link to a relative file
If you want to link to a non-AsciiDoc file that is relative to the current document, use the link macro in front of the file name.
| To link to a relative AsciiDoc file, use the xref macro instead. |
Here’s an example that demonstrates how to use the link macro to link to a relative file path:
link:downloads/report.pdf[Get Report]The AsciiDoc processor will create a link to report.pdf with the text "Get Report", even though the target is not a URL.
If the target file is an HTML file, and you want to link directly to an anchor within that document, append a hash (#) followed by the name of the anchor after the file name:
link:tools.html#editors[]Note that when linking to a relative file, even if it’s an HTML file, the link text is required.
When to use the link macro
Since AsciiDoc provides autolinks and URL macros, the link macro is not often needed. Here are the few cases when the link macro is necessary:
-
The target is not a URL (e.g., a relative path)
-
The target must be enclosed in a passthrough to escape characters with special meaning
-
The URL macro is not bounded by spaces, brackets, or quotes.
-
The target is a URL that does not start with a scheme recognized by AsciiDoc
The most common situation is when the target is not a URL. For example, you would use the link macro to create a link to a relative path.
link:report.pdf[Get Report]| If the relative path is another AsciiDoc file, you should use the xref macro instead. |
You may also discover that spaces are not permitted in the target of the link macro, at least not in the AsciiDoc source. The space character in the target prevents the parser from recognizing the macro. So it’s necessary to escape or encode it. Here are three ways to do it:
link:pass:[My Documents/report.pdf][Get Report]link:My Documents/report.pdf[Get Report]link:My%20Documents/report.pdf[Get Report]Escaping or encoding the space ensures that the space does not prevent the link macro from being recognized. The downside of using URL encoding is that it will be visible in the automatic link text since the browser does not decode it in that location. In this case, the character reference is preferable.
There are other characters that are not permitted in a link target as well, such as a colon. You can escape those using the same technique.
link:Avengers%3A%20Endgame.html[]Another common case is when you need to use a passthrough to escape characters with special meaning. In this case, the AsciiDoc processor will not recognize the target as a URL, and thus the link macro is necessary. An example is when the URL contains repeating underscore characters.
link:++https://example.org/now_this__link_works.html++[]A similar situation is when the URL macro is not bounded by spaces, brackets, or quotes. In this case, the link macro prefix is required to increase the precedence so that the macro can be recognized.
|link:https://asciidoctor.org[]|Finally, if the target is not recognized as a URL by AsciiDoc, the link macro is necessary. For example, you might use the link macro to make a file link.
link:file:///home/username[Your files]