doc: Use markdown syntax for xrefs

Syntax is taken from MyST:

https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing

3 files changed, 8 insertions, 3 deletions

diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md
index 4fa88895484..e42ba512b98 100644
--- a/doc/contributing/coding-conventions.chapter.md
+++ b/doc/contributing/coding-conventions.chapter.md
@@ -6,7 +6,7 @@
 
 - Do not use tab characters, i.e. configure your editor to use soft tabs. For instance, use `(setq-default indent-tabs-mode nil)` in Emacs. Everybody has different tab settings so it’s asking for trouble.
 
-- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in <xref linkend="sec-package-naming"/>.
+- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [](#sec-package-naming).
 
 - Function calls with attribute set arguments are written as
 
@@ -209,7 +209,7 @@ There are a few naming guidelines:
 
 - Dashes in the package name _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names.
 
-- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c-0-9` and `json-c-0-11`. If there is an obvious “default” version, make an attribute like `json-c = json-c-0-9;`. See also <xref linkend="sec-versioning" />
+- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c-0-9` and `json-c-0-11`. If there is an obvious “default” version, make an attribute like `json-c = json-c-0-9;`. See also [](#sec-versioning)
 
 ## File naming and organisation {#sec-organisation}
 
diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md
index 44feac7fbf7..2f7ae32259c 100644
--- a/doc/contributing/contributing-to-documentation.chapter.md
+++ b/doc/contributing/contributing-to-documentation.chapter.md
@@ -47,6 +47,11 @@ Additionally, the following syntax extensions are currently used:
   - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.
   ```
 
+- []{#ssec-contributing-markup-automatic-links}
+  If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example, `[](#chap-contributing)` will result in [](#chap-contributing).
+
+  This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
+
 - []{#ssec-contributing-markup-admonitions}
   **Admonitions**, set off from the text to bring attention to something.
 
diff --git a/doc/contributing/quick-start.chapter.md b/doc/contributing/quick-start.chapter.md
index 85c3897221e..96b30d3822c 100644
--- a/doc/contributing/quick-start.chapter.md
+++ b/doc/contributing/quick-start.chapter.md
@@ -9,7 +9,7 @@ To add a package to Nixpkgs:
    $ cd nixpkgs
    ```
 
-2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See <xref linkend="sec-organisation" /> for some hints on the tree organisation. Create a directory for your package, e.g.
+2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See [](#sec-organisation) for some hints on the tree organisation. Create a directory for your package, e.g.
 
    ```ShellSession
    $ mkdir pkgs/development/libraries/libfoo