diff --git a/docs/syntax/links.md b/docs/syntax/links.md
index 7f11243be..676365cf0 100644
--- a/docs/syntax/links.md
+++ b/docs/syntax/links.md
@@ -84,6 +84,10 @@ The syntax follows the format `<scheme>://<path>`, where:
 - `scheme`: The target repository name (e.g., kibana, beats)
 - `path`: The file path within that repository
 
+:::{important}
+The `path` in cross-repo links must be relative to the `docset.yml` file and not the full path within the repo
+:::
+
 ### External links
 
 Link to websites and resources outside the Elastic docs:
@@ -139,4 +143,4 @@ This syntax exists to aid with migration. It is scheduled for removal and **shou
 
 ```markdown
 Some text $$$custom-anchor$$$ more text
-```
\ No newline at end of file
+```