Link Macro Attribute Parsing

If named attributes are detected between the square brackets of a link macro (including URL macros), 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.

Linked 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://discuss.asciidoctor.org[Discuss Asciidoctor]

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. As a simplified rule, to be sure that the link text is recognized properly, it can either:

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

  • or be 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://discuss.asciidoctor.org[Discuss Asciidoctor,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, Bing",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"]

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://discuss.asciidoctor.org[role=bagel,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]

Target a blank window

Since the behavior of browsers is so widely varied, 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]

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

Since configuring an external link to target a blank window is a common practice, AsciiDoc provides a shorthand for it. Instead of having to include window=_blank in the attribute list, you can add a caret (^) to the end of the link text.

Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage^].
If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence with a backslash.

If the attribute list has both link text and named attributes, the caret should fall at the end of the link text, but inside the double quotes if present.

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