@@ -37,7 +37,7 @@ the {url-repo}/issues[Asciidoctor issue tracker]. <.>
<.> Attribute references can be used in macros.
<.> Attribute references can be used in blocks, such as xref:blocks:admonition.adoc[admonitions], and inline.
Since there isn't a blank line between the `disclaimer` reference and the next sentence, the sentence will be directly appended to the end of the attribute's value when it's processed.
<.> The reference to the `url-repo-ex` attribute is inserted into a longer URL address and used in a xref:macros:link.adoc[URL macro].
<.> The reference to the `url-repo-ex` attribute is inserted into a longer URL address and used in a xref:macros:url-macro.adoc[URL macro].
As you can see below, the attribute references are replaced with the corresponding attribute value when the document is processed.
The AsciiDoc processor will detect common URLs (unless escaped) wherever the macro substitution step is applied and automatically convert them into links.
This page documents the recognized URL schemes and how to disable this behavior on a case-by-case basis.
== URL schemes for autolinks
AsciiDoc recognizes the following common URL schemes without the help of any markup:
[#schemes]
* http
* https
* ftp
* irc
* mailto
The URL in the following example begins with a recognized protocol (i.e., https), so the AsciiDoc processor will automatically turn it into a hyperlink.
[source]
----
include::example$url.adoc[tag=base-co]
----
<.> The trailing period will not get caught up in the link.
The URL is also used as the linked text.
If you want to custom the linked text, you can use the xref:url-macro.adoc[URL macro].
In plain text documents, a bare URL is often enclosed in angle brackets.
[source]
----
You'll often see <https://example.org> used in examples.
----
To accommodate this convention, the AsciiDoc processor will still recognize the URL as an autolink, but will discard the angle brackets in the output (as they are not deemed significant).
Any link created from a bare URL (i.e., an autolink) automatically gets assigned the "bare" role.
This allows the theming system (e.g., CSS) to recognize autolinks (and other bare URLs) and style them distinctly.
== Email autolinks
AsciiDoc also detects and autolinks most email addresses.
[source]
----
include::example$url.adoc[tag=bare-email]
----
In order for this to work, the domain suffix must be between 2 and 5 characters (e.g., .com) and only common symbols like period (`.`), hyphen (`-`), and plus (`+`) are permitted.
For email address which do not conform to these restriction, you can use the xref:email-macro.adoc[email macro].
== Escaping URLs and email addresses
To prevent automatic linking of an URL or email address, add a single backslash (`\`) in front of it.
[source]
----
Once launched, the site will be available at \https://example.org.
If you cannot access the site, email \help@example.org for assistance.
----
The backslash in front of the URL and email address will not appear in the output.
The URL and email address will both be shown in plain text.
The email (i.e., mailto) macro is a specialization of the URL macro that adds support for augmenting the email link with additional metadata, namely a subject and body.
== Subject and body
Like with other URL macros, the first positional attribute of the email macro is the linked 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:
When the reader clicks the link, a conforming email client will fill in the subject line with "Subscribe me".
If you also want the body of the email to be prepopulated, specify that text in the third positional argument.
[source]
----
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.
[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.
To learn more about how the attributes are parsed, refer to xref:link-macro-attribute-parsing.adoc[attribute parsing].
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.
The following example shows a URL macro with custom linked text alongside named attributes.
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.
[source]
----
https://discuss.asciidoctor.org[,role=resource]
----
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.
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.
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.
If the window is not `_blank`, you need to enable this behavior explicitly by setting the `noopener` option on the macro:
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.
The link macro is the most explicit method of making a link in AsciiDoc.
It's only necessary when the behavior of autolinks and URL macros proves insufficient.
This page covers the anatomy of the link macro, when it's required, and how to use it.
== Anatomy
The link macro is an inline macro.
Like other inline macros, its syntax follows the familiar pattern of the macro name and target separated by a colon followed by an attribute list enclosed in square brackets.
[source]
----
link:<target>[<attrlist>]
----
The `<target>` becomes the target of the link.
the `<attrlist>` is the linked text unless a named attribute is detected.
See xref:link-macro-attribute-parsing.adoc[link macro attribute list] to learn how the `<attrlist>` is parsed.
Like all inline macros, the link macro can be escaped using a leading backslash (`\`).
Here's an example that demonstrates how to use the link macro to link to a relative path:
[source]
----
link:report.pdf[Get Report]
----
The AsciiDoc processor will create a link to _report.pdf_ with the text "Get Report", even though the target is not a URL.
// FIXME: this feels like it needs subsections
== When to use the link macro
Since AsciiDoc provides autolinks and URL macros, the link macro is not often needed.
Here are the few cases when the link macro is necessary:
* The target is not a URL (e.g., a relative path)
* The target must be enclosed in a passthrough to escape characters with special meaning
* The target contains spaces
* The URL macro is not bounded by spaces, brackets, or quotes.
* The target is a URL that does not start with a scheme recognized by AsciiDoc
The most common situation is when the target is not a URL.
For example, you would use the link macro to create a link to a relative path.
[source]
----
link:report.pdf[Get Report]
----
TIP: If the relative path is another AsciiDoc file, you should use the xref:inter-document-xref.adoc[xref macro] instead.
You may also discover that spaces are not permitted in the target, at least not as written in AsciiDoc.
The raw space character in the target prevents the parser from recognizing the macro.
So it's necessary to escape or encode it.
Here are three ways to do it:
.Escape a space using a passthrough
[source]
----
link:pass:[My Documents/report.pdf][Get Report]
----
.Encode a space using URL encoding (%20)
[source]
----
link:My%20Documents/report.pdf[Get Report]
----
.Encode a space using a character reference ( )
[source]
----
link:My Documents/report.pdf[Get Report]
----
Escaping or encoding the space ensures that the space does not disrupt the link macro.
Another common case is when you need to use a passthrough to escape characters with special meaning.
In this case, the AsciiDoc processor will not recognize the target as a URL, and thus the link macro is necessary.
An example is when the URL contains repeating underscore characters.
AsciiDoc offers a variety of ways of creating links (aka hyperlinks) to addressable resources.
The pages in this section document how to add and customize links in an AsciiDoc document.
== 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.
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.
A URL consists of a scheme, an authority (i.e., domain name), a path with optional file extension, and metadata in the form of a query string and fragment.
You may recognize the URL as what you type in the location bar of a web browser (such as the one for this page).
Since a URL has a distinct, recognizable syntax, an AsciiDoc processor will detect them (unless escaped) whereever the macro substitution step is applied and automatically convert them into links.
This also works for bare email addresses.
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.
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].
You can also use the xref:link-macro.adoc[link macro] to make a link to a target that is not recognized as a URL, such as a relative path.
When linking to an email address, you can use the specialized xref:email-macro.adoc[email macro] to enhance the link with prepopulated subject and body text.
== 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://_).
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.
[source]
----
= Document Title
:hide-uri-scheme: <1>
https://asciidoctor.org
----
<1> Note the use of `uri` instead of `url` in the attribute name.
When the `hide-uri-scheme` attribute is set, the above URL will be displayed to the reader as follows:
====
https://asciidoctor.org[asciidoctor.org]
====
Note the absence of _https://_ in the URL.
The prefix will still be present in the link target.
////
= URLs and Links
A Uniform Resource Link (URL) represents the location of a resource on the web.
...
...
@@ -34,26 +91,6 @@ To prevent automatic linking of an URL, prepend it with a backslash (`\`).
Once launched, the site will be available at \https://example.org.
----
== Hide URI schemes
If you prefer URLs to be shown with the scheme hidden, set the `hide-uri-scheme` attribute in the document's header.
[source]
----
:hide-uri-scheme:
https://asciidoctor.org
----
When the `hide-uri-scheme` attribute is set, the above URL will render as follows:
// The term URL is now preferred over the term URI. See https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#URLs_and_URNs
If you're familiar with the AsciiDoc syntax, you may notice that a URL almost looks like an inline macro.
All that's missing is the set of the trailing square brackets.
In fact, if you add them, then a URL is treated an an inline macro.
We call this a URL macro.
This page introduces the URL macro, when you would want to use it, and how it differs from the link macro.
== From URL to macro
To transform a URL into a macro, add a set of square brackets to the end of the URL.
For example:
[source]
----
https://asciidoctor.org[]
----
Since no text is specified, this macro behaves the same as an autolink.
In this case, the link automatically gets assigned the "bare" role.
When the URL is followed by a pair of square brackets, the URL scheme dually serves as the macro name.
AsciiDoc recognizes all the xref:autolinks.adoc#schemes[URL schemes] for autolinks as macro names.
That's why we say "URL macros" and not just "URL macro".
It's a family of macros.
With the exception of the xref:email-macro.adoc[mailto macro], all the URL macros behave the same, and also behave the same as the xref:link-macro.adoc[link macro].
So why might you upgrade from a URL to a URL macro?
One reason is to force the URL to be parsed when it would not normally be recognized, such as if it's enclosed in double quotes:
[source]
----
Type "https://asciidoctor.org[]" into the location bar of your browser.
----
The more typical reason, however, is to specify custom link text.
== Custom linked text
Instead of displaying the URL, you can configure the link to display custom text.
When the reader clicks on the text, they are directed to the target of the link, the URL.
To customize the text of the link, insert that text between the square brackets of the URL macro.
[source]
----
include::example$url.adoc[tag=irc]
----
Since the text is subject to normal substitutions, you can apply formatting to it.
[source]
----
include::example$url.adoc[tag=text]
----
== Link attributes
You can use the attribute list to further customize the link, such as to make it target a new window and apply a role to it.
[source]
----
include::example$url.adoc[tag=css]
----
To understand how the text between the square brackets of a URL macro is parsed, see xref:link-macro-attribute-parsing.adoc[attribute parsing].
