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 (\).

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.

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 target contains spaces

  • 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, at least not as written in AsciiDoc. The raw 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:

Example 1. Escape a space using a passthrough
link:pass:[My Documents/report.pdf][Get Report]
Example 2. Encode a space using URL encoding (%20)
link:My%20Documents/report.pdf[Get Report]
Example 3. Encode a space using a character reference (&#32;)
link:My&#32;Documents/report.pdf[Get Report]

Escaping or encoding the space ensures that the space does not disrupt the link macro.

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]

Final word

The general rule of thumb is that you should only use the link macro if it becomes necessary because, otherwise, it just adds verbosity.