URLs

On this page, you’ll learn:

  • When you should use a URL versus a cross reference.

  • How to create links with and without link text.

  • How to escape a URL.

  • How to handle complex URLs.

URL or cross reference?

Use AsciiDoc’s URL syntax when you need to create a link to an external URL. External URLs are links to webpages that aren’t built as part of your documentation site by your Antora pipeline.

When you want to link to a page, image, or attachment that is part of your documentation site, use the AsciiDoc xref macro and the resource’s resource ID instead.

URL syntax

To create a link to an external URL, all you need to do is add the URL prefixed with its scheme.

Raw URL syntax

Chat with other documentation writers at antora.zulipchat.com.

Links that begin with official schemes, such as https, ftp, mailto, etc., are automatically turned into hyperlinks when they’re processed. Here’s the result of Raw URL syntax.

Chat with other documentation writers at antora.zulipchat.com.

To attach a URL to text, enclose the text in square brackets ([]) at the end of the URL.

Example 1. URL with link text syntax
Looking for help?
Visit the https://antora.zulipchat.com[Antora chat room].

The result of Example 1 is displayed below.

Looking for help? Visit the Antora chat room.

Escape a URL

When you want to display a URL but you don’t want it to be active, you can escape it by prepending it with a backslash (\).

Example 2. Escape syntax
This URL is displayed, \https://gitlab.com, but isn't clickable.

Here’s the result of Example 2.

This URL is displayed, https://gitlab.com, but isn’t clickable.

Troubleshooting URLs

A URL may not display correctly when it contains characters such as underscores (_) or carets (^) because these characters get interpreted as text formatting markup.

There are two ways to solve this situation.

  • Option 1: Create a custom attribute for the URL.

  • Option 2: Use the inline pass macro with macros enabled.

Create an attribute for a URL

Let’s make an attribute for a complex URL. Creating an attribute for a URL is also a good strategy when the URL is long; it keeps the source text clean for writers and editors.

Example 3. Custom AsciiDoc attribute syntax
= Page Title
:url-peak: https://www.google.com/maps/place/Antora+Peak/@38.3249976,-106.2355882,14z/data=!3m1!4b1!4m5!3m4!1s0x871572433f469bd7:0xd2bdf15e615cd269!8m2!3d38.3249994!4d-106.2180786!5m1!1e4 (1)

{url-peak}[This URL] was complicated, but a page attribute came to our rescue! (2)
1 Create an attribute, with the name of your choice, in the header of your source file. Assign the URL to it.
2 When you want to create a link to that URL in your text, use the attribute (i.e., reference that attribute), as you would have used the URL.

The result of Example 3 is displayed below.

This URL was complicated, but a page attribute came to our rescue!

Use the pass macro

If you want to display a complex URL and ensure it doesn’t get caught up in any text formatting, put it inside a pass macro and enable the macros substitution, which is what substitutes links.

Here’s how a pass macro with the macros substitution enabled is constructed:

pass:macros[URL goes between these brackets]

Here’s a pass macro in action:

Example 4. Pass macro with macros substitution syntax
Anyone want to climb this 13er with me? (pass:macros[https://www.14ers.com/13ers/peak.php?peakkey=4740])

The result of Example 4 is displayed below.

Anyone want to climb this 13er with me? (www.14ers.com/13ers/peak.php?peakkey=4740)

AsciiDoc and Asciidoctor resources