merge queue: embarking 2.28-maintenance (0d763f7) and #13583 together

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.
 

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)