link-macro-attribute-parsing.adoc 4.55 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
8
9
10
11
12
13
14

== Linked text alongside named attributes

Normally, the whole text between the square brackets of a link macro is treated as the linked text.

[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
24
25
26
27
28
29
30

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]
----

31
32
Let's consider a case where the linked text contains a comma and the macro also has named attributes.
In this case, you must enclose the linked text in double quotes so that it is recognized as a single (positional) attribute.
33
34
35

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

39
Similarly, if the linked text contains an equals sign, the text may be enclosed in double quotes to assure recognition as a positional attribute.
40

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

Finally, for automatic linked text and named attributes, you simply specify the named attributes.
47
48
49

[source]
----
50
https://discuss.asciidoctor.org[role=bagel,window=_blank,opts=nofollow]
51
52
----

53
54
55
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.

56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
== 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

81
82
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.
83
84
85
86
87
88
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

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]
----
https://example.org["Google, Yahoo, Bing^",role=teal]
----