@@ -4,7 +4,7 @@ The mailto macro is a specialization of the URL macro that adds support for augm
== Subject and body
Like with other URL macros, the first positional attribute of the email macro is the linked text.
Like with other URL macros, the first positional attribute of the email macro is the link text.
If a comma is present in the text, and the text is not enclosed in quotes, or the comma comes after the closing quote, the next positional attribute is treated as subject line.
For example, you can configure the email link to prepopulate the subject line when the reader clicks the link using the following syntax:
...
...
@@ -25,12 +25,12 @@ mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to join]
When the reader clicks the link, a conforming email client will fill in the body with "I want to join".
If you want to leave the linked text blank (so it falls back to the email address), start the attribute list with a comma so as to leave a blank slot for it.
If you want to leave the link text blank (so it falls back to the email address), start the attribute list with a comma so as to leave a blank slot for it.
[source]
----
mailto:join@discuss.example.org[,Subscribe me,I want to join]
----
If either the linked text, subject, or body contains a comma, that value must be enclosed in double quotes.
If either the link text, subject, or body contains a comma, that value must be enclosed in double quotes.
To learn more about how the attributes are parsed, refer to xref:link-macro-attribute-parsing.adoc[attribute parsing].
@@ -98,5 +98,5 @@ To solve this problem, you can define the following two attributes:
:relfilesuffix: /
----
Now, the cross reference `+<<filename.adoc,linked text>>+` will resolve to [.path]_../filename_ instead of [.path]_filename.html_.
Now, the cross reference `+<<filename.adoc,link text>>+` will resolve to [.path]_../filename_ instead of [.path]_filename.html_.
Since this change is specific to the website architecture described, you want to be sure to only set these attributes in that particular environment (either using an ifdef directive or via the API).
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:
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 linked text.
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 linked text alongside named attributes.
The following example shows a URL macro with custom link text alongside named attributes.
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.
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.
[source]
----
https://example.org["1=2 posits the problem of inequality"]
----
The double quote enclosure is not required in all cases when the linked text contains an equals sign.
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 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).
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).
[source]
----
...
...
@@ -114,7 +114,7 @@ To fine tune indexing within the site, you can specify the nofollow option even
=== 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.
Instead of having to include `window=_blank` in the attribute list, you can add a caret (`+^+`) to the end of the link text.
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.
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.
@@ -7,7 +7,7 @@ The pages in this section document how to add and customize links in an AsciiDoc
== URLs and links
The target of a link is a {url-url-def}[Uniform Resource Locator^] (URL), otherwise known as a web address.
The text you click to be navigate to that target is referred to as the linked text.
The text you click to be navigate to that target is referred to as the link text.
NOTE: You may sometimes see the term URI used in place of a URL.
Although the URI is more technically correct in some cases, URL is the accepted term.
...
...
@@ -21,7 +21,7 @@ You can learn more about this behavior in xref:autolinks.adoc[].
== Link-related macros
Instead of showing the bare URL or email address as the linked text, you may want to customize that text.
Instead of showing the bare URL or email address as the link text, you may want to customize that text.
Or perhaps you want to apply attributes to the link, such as a role.
To do so, you'd use either the xref:url-macro.adoc[URL macro] or, if you're linking to xref:complex-urls.adoc[a complex URL], the more explicit xref:link-macro.adoc[link macro].
...
...
@@ -32,7 +32,7 @@ When linking to an email address, you can use the specialized xref:email-macro.a
[#hide-uri-scheme]
== Hide the URL scheme
If the linked text is a bare URL (aka URI), whether that link was created automatically or using a link-related macro, you can configure the AsciiDoc processor to hide the scheme (e.g., _https://_).
If the link text is a bare URL (aka URI), whether that link was created automatically or using a link-related macro, you can configure the AsciiDoc processor to hide the scheme (e.g., _https://_).
Hiding the scheme can make the URL more readable--perhaps even recognizable--to a person less familiar with technical nomenclature.
To configure the AsciiDoc processor to display the linked URL without the scheme part, set the `hide-uri-scheme` attribute in the header of the AsciiDoc document.