Commit 59a0035c authored by Dan Allen's avatar Dan Allen
Browse files

clarify how link text is parsed in relation to named attributes (PR #33)

* rewrite much of the description of link attribute parsing to reflect the simplified parsing behavior implemented in https://github.com/asciidoctor/asciidoctor/issues/2059
* remove the detail about how positional attributes are parsed, which will be covered in a dedicated page

Authored by: David Jencks <djencks@apache.org>
parent d4f97063
......@@ -4,6 +4,11 @@ This document summarizes the changes introduced to the AsciiDoc Language Documen
For a detailed view of what's changed, refer to the repository's
https://github.com/asciidoctor/asciidoc-docs/commits/main[commit history].
== Published Q1 2021
Fixed::
* Rewrite much of link-macro-attribute-parsing.adoc to reflect the simplified parsing behavior implemented in https://github.com/asciidoctor/asciidoctor/issues/2059.
== Published Q4 2020
These changes were committed and merged into the main branch starting on November 24, 2020.
......
= 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 linked text so it does not get caught up in this parsing.
This page explains the conditions when this occurs and how to write the linked text so it is recognized as a single positional attribute.
== Linked text alongside named attributes
......@@ -12,8 +12,14 @@ Normally, the whole text between the square brackets of a link macro is treated
https://discuss.asciidoctor.org[Discuss Asciidoctor]
----
However, if the text contains both an equals sign (`=`) and a comma (`,`), and the comma comes after the equals sign, the text is parsed as an attribute list.
In this case, the linked text is the first positional attribute.
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.
The following example shows a URL macro with custom linked text alongside named attributes.
......@@ -22,26 +28,31 @@ The following example shows a URL macro with custom linked text alongside named
https://discuss.asciidoctor.org[Discuss Asciidoctor,role=resource,window=_blank]
----
If you want to define a single named attribute, but leave the linked text empty (so it falls back to the URL), then you need to start the attribute list with a comma.
In other words, you need to leave a slot for the linked text so that the parser knows where it ends.
Otherwise, the parser will treat the named attribute as the linked text.
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.
[source]
----
https://discuss.asciidoctor.org[,role=resource]
https://example.org["Google, Yahoo, Bing",role=teal]
----
When attribute parsing is enabled, 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.
Similarly, if the linked text contains an equals sign, the text may be enclosed in double quotes to assure recognition as a positional attribute.
Let's consider a case when the linked text contains a comma and macro also has named attributes.
In this case, you must enclose the linked text in double quotes so that it gets preserved by the parser.
[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.
[source]
----
https://example.org["Google, Yahoo, Bing",role=teal]
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.
......@@ -67,8 +78,8 @@ https://asciidoctor.org[Asciidoctor,window=_blank]
=== noopener and nofollow
When the value of the `window` attribute is `_blank`, the AsciiDoc processor should also add the `rel="noopener"` attribute to the link tag in the HTML output.
Doing so is considered a security best pratice.
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.
If the window is not `_blank`, you need to enable this behavior explicitly by setting the `noopener` option on the macro:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment