Commit 82e83e6a authored by Dan Allen's avatar Dan Allen
Browse files

reorganize and rewrite section about links

parent 490db107
......@@ -645,16 +645,7 @@ See https://docs.mathjax.org/en/v2.5-latest/tex.html#automatic-equation-numberin
|_empty_
|{y}
|
|xref:macros:link.adoc#hide-uri-schemes[Hides URI scheme] for raw links.
|linkattrs
|{n}
|_empty_
|{y}
|
|xref:macros:link.adoc#link-macro-attributes[Parse attributes inside link macros].
Removed in Asciidoctor 1.5.7.
Attributes are now parsed automatically if an equal sign is found after a comma (e.g., `[link text,window=_blank]`).
|xref:macros:links.adoc#hide-the-uri-scheme[Hides URI scheme] for raw links.
|media
|{n}
......
......@@ -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.
......
......@@ -66,6 +66,10 @@ https://asciidoctor.org[Asciidoctor]
https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
// end::b-base[]
// tag::bare-email[]
Email us at hello@example.com to say hello.
// end::bare-email[]
// tag::b-scheme[]
devel@discuss.arquillian.org
......
* xref:link.adoc[]
** xref:relative-link.adoc[]
** xref:link-ref.adoc[]
* xref:links.adoc[]
** xref:autolinks.adoc[]
** xref:url-macro.adoc[]
** xref:email-macro.adoc[]
** xref:link-macro.adoc[]
** xref:link-macro-attribute-parsing.adoc[]
** xref:complex-urls.adoc[]
** xref:link-macro-ref.adoc[]
* xref:xref.adoc[]
** xref:inter-document-xref.adoc[]
** xref:xref-text-and-style.adoc[]
......
= Autolinks
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.
= Troubleshooting Complex URLs
A URL may not display correctly when it contains characters such as underscores (`+_+`) or carets (`+^`).
include::partial$ts-url-format.adoc[tag=sb]
= Email (mailto) Macro
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:
[source]
----
mailto:join@discuss.example.org[Subscribe,Subscribe me]
----
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].
= 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.
== 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]
----
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.
[source]
----
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.
[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.
[source]
----
https://example.org["Google, Yahoo, Bing",role=teal]
----
== 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
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:
[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]
----
= URL and Link Attributes Reference
= Link Macro Attributes Reference
These attributes apply to the link, URL, and email macros.
[%autowidth]
|===
|Attribute |Value(s) |Example Syntax |Comments
|`linkattrs`
|`id`
|Unique identifier for element in output
|++https://asciidoctor.org[Home,id=home]++
|
|`role`
|CSS classes available to inline elements
|++https://discuss.asciidoctor.org[Discuss Asciidoctor,role=teal]++
|
|`title`
|Description of link, often show as tooltip.
|++https://asciidoctor.org[Home,title=Project home page]++
|
|`:linkattrs:`
|Prior to 1.5.7, must be set in the header to parse link macro attributes.
Since 1.5.7, attributes are parsed automatically if an equal sign is found after a comma (e.g., `[link text,window=_blank]`).
|`window`
|any
|++https://discuss.asciidoctor.org[Discuss Asciidoctor,window=_blank]++
|The blank window target can also be specified using `^` at the end of the link text.
|`window`
|`window` +
(shorthand)
|`^`
|++https://example.org["Google, Yahoo, Bing^"]++ and ++https://discuss.asciidoctor.org[Discuss Asciidoctor^]++
|
|`role`
|CSS classes available to inline elements
|++https://discuss.asciidoctor.org[Discuss Asciidoctor,role=teal]++
|
|`id`
|name of element, custom link text
|++<<section-title,cross reference text>>++
|Applies to cross references.
|`opts`
|Additional options for link creation.
|++https://asciidoctor.org[Home,id=home]++
|Option names include: `nofollow`, `noopener`
|===
= Link Macro
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 (&#32;)
[source]
----
link:My&#32;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.
[source]
----
link:++https://example.org/now_this__link_works.html++[]
----
A similar situation is when the URL macro is not bounded by spaces, brackets, or quotes.
In this case, the link macro prefix is required to increase the precedence so that the macro can be recognized.
[source]
----
|link:https://asciidoctor.org[]|
----
Finally, if the target is not recognized as a URL by AsciiDoc, the link macro is necessary.
For example, you might use the link macro to make a file link.
[source]
----
link:file:///home/username[Your files]
----
== Final word
The general rule of thumb is that you should only use the link macro if it becomes necessary because, otherwise, it just adds verbosity.
= Links
:url-url-def: https://en.wikipedia.org/wiki/URL
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:
[source,xml]
----
<a href="https://asciidoctor.org">asciidoctor.org</a>
----
Note the absence of _https_ in the contents of the `<a>` element.
== Link text
To attach a URL to text, enclose the text in square brackets at the end of the URL, thus making it a URL macro.
......@@ -165,3 +202,4 @@ include::example$url.adoc[tag=css]
TIP: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor.
When they're enabled, you must surround the link text in double quotes if it contains a comma.
// end::attr[]
////
= URL Macro(s)
// 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].
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