diff --git a/doc/manual/source/development/contributing.md b/doc/manual/source/development/contributing.md
index 7de7489dc..5c32aeb71 100644
--- a/doc/manual/source/development/contributing.md
+++ b/doc/manual/source/development/contributing.md
@@ -20,8 +20,9 @@ prs: 1238
 Here's one or more paragraphs that describe the change.
 
 - It's markdown
-- Add references to the manual using @docroot@
+- Add references to the manual using [links like this](@_at_docroot@/example.md)
 ```
+<!-- for the raw markdown readers: that means using @docroot@ -->
 
 Significant changes should add the following header, which moves them to the top.
 
diff --git a/doc/manual/substitute.py b/doc/manual/substitute.py
index a8b11d932..6e27c3388 100644
--- a/doc/manual/substitute.py
+++ b/doc/manual/substitute.py
@@ -57,6 +57,9 @@ def recursive_replace(data: dict[str, t.Any], book_root: Path, search_path: Path
                     ).replace(
                         '@docroot@',
                         ("../" * len(path_to_chapter.parent.parts) or "./")[:-1]
+                    ).replace(
+                        '@_at_',
+                        '@'
                     ),
                     sub_items = [
                         recursive_replace(sub_item, book_root, search_path)