link-macro-attribute-parsing.adoc 5.07 KB
Newer Older
1
2
3
= 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.
4
This page explains the conditions when this occurs and how to write the linked text so it is recognized as a single positional attribute.
5
6
7

== Linked text alongside named attributes

8
Normally, the whole text between the square brackets of a link macro is treated as the linked text (i.e., the first positional attribute).
9
10
11
12
13
14

[source]
----
https://discuss.asciidoctor.org[Discuss Asciidoctor]
----

15
16
17
18
19
20
21
22
However, if the text contains an equals sign (`=`), the text is parsed as an xref:attributes:element-attributes.adoc#attribute-list[attribute list].
The exact rules for attribute list parsing and positional attributes are rather complex, and discussed on xref:attributes:positional-and-named-attributes.adoc[].
As a simplified rule, to be sure that the linked 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 linked text.
23
Let's consider some examples.
24
25
26
27
28
29
30
31

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

[source]
----
https://discuss.asciidoctor.org[Discuss Asciidoctor,role=resource,window=_blank]
----

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

[source]
----
37
https://example.org["Google, DuckDuckGo, Bing",role=teal]
38
39
----

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

42
43
44
45
46
[source]
----
https://example.org["1=2 posits the problem of inequality"]
----

47
48
49
50
51
52
The double quote enclosure is not required in all cases when the linked 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 linked 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 linked text).
53
54
55

[source]
----
56
https://discuss.asciidoctor.org[role=bagel,window=_blank,opts=nofollow]
57
58
----

59
60
61
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.

62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
== 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.

[source]
----
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`.

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

=== noopener and nofollow

87
88
When the value of the `window` attribute is `_blank`, the AsciiDoc processor will also add the `rel="noopener"` attribute to the link tag in the HTML output.
Doing so is considered a security best practice.
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

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

[source]
----
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.

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

or

[source]
----
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 linked text.

[source]
----
include::example$url.adoc[tag=linkattrs-s]
----

CAUTION: 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 linked text and named attributes, the caret should fall at the end of the linked text, but inside the double quotes if present.

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