Autolinks

The AsciiDoc processor will detect common URLs (unless escaped) wherever the macros substitution step is applied and automatically convert them into links. This page documents the recognized URL schemes and how to disable this behavior on a case-by-case basis.

AsciiDoc recognizes the following common URL schemes without the help of any markup:

  • http

  • https

  • ftp

  • irc

  • mailto

The URL in the following example begins with a recognized protocol (i.e., https), so the AsciiDoc processor will automatically turn it into a hyperlink.

The homepage for the Asciidoctor Project is https://www.asciidoctor.org. (1)
1 The trailing period will not get caught up in the link.

The URL is also used as the link text. If you want to use custom link text, you must use the URL macro.

In plain text documents, a bare URL is often enclosed in angle brackets.

You'll often see <https://example.org> used in examples.

To accommodate this convention, the AsciiDoc processor will still recognize the URL as an autolink, but will discard the angle brackets in the output (as they are not deemed significant).

Any link created from a bare URL (i.e., an autolink) automatically gets assigned the "bare" role. This allows the theming system (e.g., CSS) to recognize autolinks (and other bare URLs) and style them distinctly.

AsciiDoc also detects and autolinks most email addresses.

Email us at hello@example.com to say hello.

In order for this to work, the domain suffix must be between 2 and 5 characters (e.g., .com) and only common symbols like period (.), hyphen (-), and plus (+) are permitted. For email address which do not conform to these restriction, you can use the email macro.

Escaping URLs and email addresses

To prevent automatic linking of a URL or email address, you can add a single backslash (\) in front of it.

Once launched, the site will be available at \https://example.org.

If you cannot access the site, email \help@example.org for assistance.

The backslash in front of the URL and email address will not appear in the output. The URL and email address will both be shown in plain text.

Since autolinks are a feature of the macros substitution, another way to prevent automatic linking of a URL or email address is to turn off the macros substitution using incremental subs.

[subs=-macros]
Once launched, the site will be available at https://example.org.

The subs attribute is only recognized on a leaf block, such as a paragraph.