diff --git a/docs/CHANGELOG.adoc b/docs/CHANGELOG.adoc
index 847ca7bf5dc3562902f85f28bbb2f9cd8edc05ac..c911715be1495a20d0fc1f36d0865508dccd582f 100644
--- a/docs/CHANGELOG.adoc
+++ b/docs/CHANGELOG.adoc
@@ -11,6 +11,7 @@ Added::
 
 Changed::
 * Clarify that an open block can only masquarade as other paragraph or delimited blocks
+* Clarify how a dot is handled in an xref target by the shorthand xref and the xref macro
 
 == Published Q2 2023
 
diff --git a/docs/modules/macros/pages/xref.adoc b/docs/modules/macros/pages/xref.adoc
index 6e7cfbe0942f7b9fba2f6e83bd7586bdef929bda..91fe86b3c60a9e723303f4ef4939e469dcc20a98 100644
--- a/docs/modules/macros/pages/xref.adoc
+++ b/docs/modules/macros/pages/xref.adoc
@@ -79,6 +79,8 @@ After the ID, add a comma and then enter the custom text you want the cross refe
 include::example$xref.adoc[tag=text]
 ----
 
+In this case, the target will be assumed to be an ID within the same document even if it contains a dot (`.`).
+
 You can also use the inline xref macro as an alternative to the xref shorthand.
 
 .Inline xref macro
@@ -89,6 +91,9 @@ include::example$xref.adoc[tag=xref-macro]
 
 However, it's best to reserve the use of the xref macro for creating interdocument cross references.
 
+When using the xref macro, if the target contains a dot (`.`), it will be treated as a reference to another document, not an ID within the same document.
+If the intention is to link to an ID within the same document, the target must be proceeded by a hash (`#`).
+
 === Natural cross reference
 
 You can also create a reference to a block or section using its title rather than its ID.