diff --git a/modules/macros/examples/url.adoc b/modules/macros/examples/url.adoc
index 23cb30c35dd72d6c6b950978edc95c8470e9cf9a..2f4518fbe559b6155ac1fa23b2f8abda16f7a0ee 100644
--- a/modules/macros/examples/url.adoc
+++ b/modules/macros/examples/url.adoc
@@ -45,11 +45,11 @@ Chat with other Asciidoctor users on the https://discuss.asciidoctor.org/[*maili
 // end::css[]
 
 // tag::link[]
-link:protocol.json[Open the JSON file]
+link:downloads/report.pdf[Get Report]
 // end::link[]
 
 // tag::hash[]
-link:external.html#livereload[LiveReload]
+link:tools.html#editors[]
 // end::hash[]
 
 // used in qr
diff --git a/modules/macros/examples/xref.adoc b/modules/macros/examples/xref.adoc
index 96fa374b65ca7449e4a413a91369fb0b51ee597e..f6431836f95067c31cc4849f08ace5f90da4f38f 100644
--- a/modules/macros/examples/xref.adoc
+++ b/modules/macros/examples/xref.adoc
@@ -25,11 +25,11 @@ Refer to link:document-b.html#section-b[Section B] for more information.
 // end::bad[]
 
 // tag::base-inter[]
-Refer to <<document-b.adoc#section-b,Section B>> for more information.
+Refer to xref:document-b.adoc#section-b[Section B] for more information.
 // end::base-inter[]
 
 // tag::base-inter-top[]
-Refer to <<document-b.adoc#,Document B>> for more information.
+Refer to xref:document-b.adoc[Document B] for more information.
 // end::base-inter-top[]
 
 // used in qr
diff --git a/modules/macros/pages/inter-document-xref.adoc b/modules/macros/pages/inter-document-xref.adoc
index e20a762ba01985fd451f9e0d812a93370590b00a..4f5557cd26201b9a8f1002e7add1144771398ef0 100644
--- a/modules/macros/pages/inter-document-xref.adoc
+++ b/modules/macros/pages/inter-document-xref.adoc
@@ -71,7 +71,7 @@ The following example demonstrates how to use the `relfilesuffix` attribute to c
 = Document Title
 \ifdef::env-github,env-browser[:relfilesuffix: .adoc]
 
-See the <<README#,README>>.
+See the xref:README.adoc[README].
 
 We could also write the link as link:README{relfilesuffix}[README].
 ----
diff --git a/modules/macros/pages/link-macro.adoc b/modules/macros/pages/link-macro.adoc
index 9b26a934512de4ac52957fcba7ff92c6254592c6..f53809c63c0a93de9f7a453fe45b94edf381b38a 100644
--- a/modules/macros/pages/link-macro.adoc
+++ b/modules/macros/pages/link-macro.adoc
@@ -20,15 +20,30 @@ See xref:link-macro-attribute-parsing.adoc[link macro attribute list] to learn h
 
 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:
+== Link to a relative file
+
+If you want to link to a non-AsciiDoc file that is relative to the current document, use the `link` macro in front of the file name.
+
+TIP: To link to a relative AsciiDoc file, use the xref:inter-document-xref.adoc[xref macro] instead.
+
+Here's an example that demonstrates how to use the link macro to link to a relative file path:
 
 [source]
 ----
-link:report.pdf[Get Report]
+include::example$url.adoc[tag=link]
 ----
 
 The AsciiDoc processor will create a link to _report.pdf_ with the text "Get Report", even though the target is not a URL.
 
+If the target file is an HTML file, and you want to link directly to an anchor within that document, append a hash (`#`) followed by the name of the anchor after the file name:
+
+[source]
+----
+include::example$url.adoc[tag=hash]
+----
+
+Note that when linking to a relative file, even if it's an HTML file, the linked text is required.
+
 // FIXME: this feels like it needs subsections
 == When to use the link macro
 
diff --git a/modules/macros/pages/relative-link.adoc b/modules/macros/pages/relative-link.adoc
deleted file mode 100644
index 60c4f304e718c4e6f106495f29e1cbbee1a440f7..0000000000000000000000000000000000000000
--- a/modules/macros/pages/relative-link.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-= Link to Relative Files
-
-If you want to link to an external file relative to the current document, use the `link` macro in front of the file name.
-
-[source]
-----
-include::example$url.adoc[tag=link]
-----
-
-If your file is an HTML file, you can link directly to a section in the document, append a hash (`#`) followed by the section's ID to the end of the file name.
-
-[source]
-----
-include::example$url.adoc[tag=hash]
-----
-
-////
-You can also create links that refer to sections within the current document.
-
-[source]
-----
-link:user-manual.html[URLs]
-----
-
-====
-link:user-manual.html[URLs]
-====
-////