Links
AsciiDoc offers a variety of ways of creating links (aka hyperlinks) to addressable resources. The pages in this section document how to add and customize links in an AsciiDoc document.
URLs and links
The target of a link is a Uniform Resource Locator (URL), otherwise known as a web address. The text you click to be navigate to that target is referred to as the link text.
| You may sometimes see the term URI used in place of a URL. Although the URI is more technically correct in some cases, URL is the accepted term. |
A URL consists of a scheme, an authority (i.e., domain name), a path with optional file extension, and metadata in the form of a query string and fragment. You may recognize the URL as what you type in the location bar of a web browser (such as the one for this page).
Since a URL has a distinct, recognizable syntax, an AsciiDoc processor will detect them (unless escaped) wherever the macro substitution step is applied and automatically convert them into links. This also works for bare email addresses. You can learn more about this behavior in Autolinks.
Link-related macros
Instead of showing the bare URL or email address as the link text, you may want to customize that text. Or perhaps you want to apply attributes to the link, such as a role. To do so, you’d use either the URL macro or, if you’re linking to a complex URL, the more explicit link macro.
You can also use the link macro to make a link to a target that is not recognized as a URL, such as a relative path.
When linking to an email address, you can use the specialized email macro to enhance the link with prepopulated subject and body text.
Hide the URL scheme
If the link text is a bare URL (aka URI), whether that link was created automatically or using a link-related macro, you can configure the AsciiDoc processor to hide the scheme (e.g., https://). Hiding the scheme can make the URL more readable—perhaps even recognizable—to a person less familiar with technical nomenclature.
To configure the AsciiDoc processor to display the linked URL without the scheme part, set the hide-uri-scheme attribute in the header of the AsciiDoc document.
= Document Title
:hide-uri-scheme: (1)
https://asciidoctor.org| 1 | Note the use of uri instead of url in the attribute name. |
When the hide-uri-scheme attribute is set, the above URL will be displayed to the reader as follows:
Note the absence of https:// in the URL. The prefix will still be present in the link target.