AsciiDoc offers a variety of ways of creating links (aka hyperlinks) to other addressable resources. The pages in this section document how to add and customize links in AsciiDoc.
URLs and links
The target of a link is a Uniform Resource Locator (URL), otherwise known as a web address. The text the reader clicks to 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.|
The URL is the web address of a unique resource.
A URL can either be absolute or relative.
An absolute URL consists of a scheme, an authority (i.e., domain name), a path with an optional file extension, and metadata in the form of a query string and fragment (e.g.,
You may recognize an absolute URL as what you type in the location bar of a web browser, such as the one for this page.
A relative URL is the portion of an absolute URL that starts after either the root path or a subpath (e.g.,
Since an absolute URL has a distinct, recognizable syntax, an AsciiDoc processor will detect URLs (unless escaped) and automatically convert them to links wherever the macros substitution step is applied. This also works for bare email addresses. You can learn more about this behavior in Autolinks. To make a link to a relative URL, you must be specify it explicitly as the target of a link macro.
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 decisive link macro. (You can also use the link macro to make a link to an addressable resource using a relative URL or a URL that is not otherwise recognized as an absolute URL).
When linking to an email address, you can use the specialized mailto macro to enhance the link with prepopulated subject and body text.
Encode reserved characters
If the URL contains reserved characters, such as double quote (
"), space, or an unconstrained AsciiDoc formatting mark, you’ll need to encode these characters using URI encoding.
For example, a double quote is encoded as
An underscore is encoded as
If you do not encode these characters, the URL may be mangled or cause the processor to fail.
Let’s assume we are creating a URL that contains a query string parameter named
q that contains reserved characters:
To encode a URL, open the development tools in your browser and pass the URL to the
Here’s the encoded URL that we’d use in the AsciiDoc document:
Depending on the capabilities of the web application, the space character can be encoded as
+ instead of
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
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.