Link & URL Macro Attribute Parsing

If named attributes are detected between the square brackets of a link or URL macro, that text is parsed as an attribute list. This page explains the conditions when this occurs and how to write the link text so it is recognized as a single positional attribute.

Link text alongside named attributes

Normally, the whole text between the square brackets of a link macro is treated as the link text (i.e., the first positional attribute).

https://chat.asciidoc.org[Discuss AsciiDoc]

However, if the text contains an equals sign (=), the text is parsed as an attribute list. The exact rules for attribute list parsing and positional attributes are rather complex, and discussed on Positional and Named Attributes. To be sure the link text is recognized properly, you can apply these two simple checks:

  • contains no comma (,) or equals sign (=) or

  • enclosed in double quotes (")

There are several other situations in which text before the first comma may be recognized as the link text. Let’s consider some examples.

The following example shows a URL macro with custom link text alongside named attributes.

https://chat.asciidoc.org[Discuss AsciiDoc,role=resource,window=_blank]

Let’s consider a case where the link text contains a comma and the macro also has named attributes. In this case, you must enclose the link text in double quotes so that it is capture in its entirety as the first positional attribute.

https://example.org["Google, DuckDuckGo, Ecosia",role=teal]

Similarly, if the link text contains an equals sign, you can enclose the link text in double quotes to ensure the parser recognizes it as the first positional attribute.

https://example.org["1=2 posits the problem of inequality"]

If the quoted link text itself contains the quote character used to enclose the text, escape the quote character in the text by prefixing it with a backslash.

https://example.org["href=\"#top\" attribute"] creates link to top of page

The double quote enclosure is not required in all cases when the link text contains an equals sign. Strictly speaking, the enclosure is only required when the text preceding the equals sign matches a valid attribute name. However, it’s best to use the double quotes just to be safe.

Finally, to use named attributes without specifying link text, you simply specify the named attributes. (In other words, you leave the first positional attribute empty, in which case the target will be used as the link text).

https://chat.asciidoc.org[role=button,window=_blank,opts=nofollow]

The link macro recognizes all the common attributes (id, role, and opts). It also recognizes a handful of attributes that are specific to the link macro.

Target a separate window

By default, the link produced by a link macro will target the current window. In other words, clicking on it will replace the current page.

You can configure the link to open in a separate window (or tab) using the window attribute.

https://asciidoctor.org[Asciidoctor,window=read-later]

In the HTML output, the value of the window attribute is assigned to the target attribute on the <a> tag (e.g., target=read-later).

Target a blank window

Most of the time, you’ll use the window attribute to target a blank window. Configuring a link that points to a location outside the current site is common practice to avoid disrupting the reader’s flow. To enable this behavior, you set the window attribute to the special value _blank.

https://asciidoctor.org[Asciidoctor,window=_blank]

In the HTML output, the value of the window attribute is assigned to the target attribute on the <a> tag (e.g., target=_blank) along with the rel=noopener attribute.

The underscore at the start of the value _blank can unexpectedly form a constrained formatting pair when another underscore appears somewhere else in the line or paragraph, thus causing the macro to break. You can avoid this problem either by escaping the underscore at the start of the value (i.e., window=\_blank) or by using the Blank window shorthand instead.

noopener and nofollow

When the value of the window attribute is _blank, the AsciiDoc processor will also add the rel="noopener" attribute to the <a> element in the HTML output. Doing so is considered a security best practice.

If the window is not _blank, you need to enable this behavior explicitly by setting the noopener option on the macro:

https://asciidoctor.org[Asciidoctor,window=read-later,opts=noopener]

If you don’t want the search indexer to follow the link, you can add the nofollow option to the macro. This option only works if the noopener option is set either implicitly or explicitly.

https://asciidoctor.org[Asciidoctor,window=_blank,opts=nofollow]

or

https://asciidoctor.org[Asciidoctor,window=read-later,opts="noopener,nofollow"]

To fine tune indexing within the site, you can specify the nofollow option even when the link does not target a separate window.

Blank window shorthand

Configuring an external link to target a blank window is a common practice. Therefore, AsciiDoc provides a shorthand for it.

In place of the named attribute window=_blank, you can insert a caret (^) at the end of the link text. This syntax has the added benefit of not having to worry about the underscore at the start of the value _blank unexpectedly forming a constrained formatting pair when another underscore appears in the same line or paragraph.

Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage^].
In rare circumstances, if you use the caret syntax more than once in the same line or paragraph, you may need to escape the first occurrence with a backslash. However, the processor should try to avoid making this a requirement.

If the attribute list has both link text in double quotes and named attributes, the caret should be placed at the end of the link text, but inside the double quotes.

https://example.org["Google, DuckDuckGo, Ecosia^",role=btn]

If no named attributes are present, the link text should not be enclosed in quotes.

https://example.org[Google, DuckDuckGo, Ecosia^]