Merge pull request #125838 from jtojnar/strict-commonmark

doc: Parse as CommonMark

48 files changed, 586 insertions, 415 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 7affbb0bb51c..85d09f3ddc0e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,5 +1,15 @@
 MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))
 
+PANDOC ?= pandoc
+
+pandoc_media_dir = media
+# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
+pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
+pandoc_flags = --extract-media=$(pandoc_media_dir) \
+	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
+	--lua-filter=labelless-link-is-xref.lua \
+	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
+
 .PHONY: all
 all: validate format out/html/index.html out/epub/manual.epub
 
@@ -39,7 +49,7 @@ out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
 	mkdir -p out/html/highlightjs/
 	cp -r highlightjs out/html/
 
-	cp -r media out/html/
+	cp -r $(pandoc_media_dir) out/html/
 	cp ./overrides.css out/html/
 	cp ./style.css out/html/style.css
 
@@ -54,7 +64,7 @@ out/epub/manual.epub: manual-full.xml
 		doc-support/result/epub.xsl \
 		./manual-full.xml
 
-	cp -r media out/epub/scratch/OEBPS
+	cp -r $(pandoc_media_dir) out/epub/scratch/OEBPS
 	cp ./overrides.css out/epub/scratch/OEBPS
 	cp ./style.css out/epub/scratch/OEBPS
 	mkdir -p out/epub/scratch/OEBPS/images/callouts/
@@ -89,16 +99,12 @@ functions/library/generated: doc-support/result
 	ln -rfs ./doc-support/result/function-docs functions/library/generated
 
 %.section.xml: %.section.md
-	pandoc $^ -t docbook \
-		--extract-media=media \
-		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
-		-f markdown+smart \
+	$(PANDOC) $^ -t docbook \
+		$(pandoc_flags) \
 	| cat  > $@
 
 %.chapter.xml: %.chapter.md
-	pandoc $^ -t docbook \
+	$(PANDOC) $^ -t docbook \
 		--top-level-division=chapter \
-		--extract-media=media \
-		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
-		-f markdown+smart \
+		$(pandoc_flags) \
 	| cat  > $@
diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md
index c70e3020bbfa..30d065344852 100644
--- a/doc/builders/fetchers.chapter.md
+++ b/doc/builders/fetchers.chapter.md
@@ -20,59 +20,58 @@ The main difference between `fetchurl` and `fetchzip` is in how they store the c
 
 `fetchpatch` works very similarly to `fetchurl` with the same arguments expected. It expects patch files as a source and performs normalization on them before computing the checksum. For example it will remove comments or other unstable parts that are sometimes added by version control systems and can change over time.
 
-
 Other fetcher functions allow you to add source code directly from a VCS such as subversion or git. These are mostly straightforward nambes based on the name of the command used with the VCS system. Because they give you a working repository, they act most like `fetchzip`.
 
-## `fetchsvn`
+## `fetchsvn` {#fetchsvn}
 
 Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `sha256`.
 
-## `fetchgit`
+## `fetchgit` {#fetchgit}
 
 Used with Git. Expects `url` to a Git repo, `rev`, and `sha256`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.
 
 Additionally the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout.
 
-## `fetchfossil`
+## `fetchfossil` {#fetchfossil}
 
 Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `sha256`.
 
-## `fetchcvs`
+## `fetchcvs` {#fetchcvs}
 
 Used with CVS. Expects `cvsRoot`, `tag`, and `sha256`.
 
-## `fetchhg`
+## `fetchhg` {#fetchhg}
 
 Used with Mercurial. Expects `url`, `rev`, and `sha256`.
 
 A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are mainly convenience functions intended for commonly used destinations of source code in Nixpkgs. These wrapper fetchers are listed below.
 
-## `fetchFromGitHub`
+## `fetchFromGitHub` {#fetchfromgithub}
 
 `fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `sha256` is currently preferred.
 
 `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options.
 
-## `fetchFromGitLab`
+## `fetchFromGitLab` {#fetchfromgitlab}
 
 This is used with GitLab repositories. The arguments expected are very similar to fetchFromGitHub above.
 
-## `fetchFromGitiles`
+## `fetchFromGitiles` {#fetchfromgitiles}
 
 This is used with Gitiles repositories. The arguments expected are similar to fetchgit.
 
-## `fetchFromBitbucket`
+## `fetchFromBitbucket` {#fetchfrombitbucket}
 
 This is used with BitBucket repositories. The arguments expected are very similar to fetchFromGitHub above.
 
-## `fetchFromSavannah`
+## `fetchFromSavannah` {#fetchfromsavannah}
 
 This is used with Savannah repositories. The arguments expected are very similar to fetchFromGitHub above.
 
-## `fetchFromRepoOrCz`
+## `fetchFromRepoOrCz` {#fetchfromrepoorcz}
 
 This is used with repo.or.cz repositories. The arguments expected are very similar to fetchFromGitHub above.
 
-## `fetchFromSourcehut`
+## `fetchFromSourcehut` {#fetchfromsourcehut}
 
 This is used with sourcehut repositories. The arguments expected are very similar to fetchFromGitHub above. Don't forget the tilde (~) in front of the user name!
diff --git a/doc/builders/images/appimagetools.section.md b/doc/builders/images/appimagetools.section.md
index 7ab4e4e9d855..67e63dc5f61a 100644
--- a/doc/builders/images/appimagetools.section.md
+++ b/doc/builders/images/appimagetools.section.md
@@ -2,7 +2,7 @@
 
 `pkgs.appimageTools` is a set of functions for extracting and wrapping [AppImage](https://appimage.org/) files. They are meant to be used if traditional packaging from source is infeasible, or it would take too long. To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.
 
-::: warning
+::: {.warning}
 The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future.
 :::
 
diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md
index 2d21eb1c2e07..bfe1d17a6067 100644
--- a/doc/builders/images/dockertools.section.md
+++ b/doc/builders/images/dockertools.section.md
@@ -1,6 +1,6 @@
 # pkgs.dockerTools {#sec-pkgs-dockerTools}
 
-`pkgs.dockerTools` is a set of functions for creating and manipulating Docker images according to the [ Docker Image Specification v1.2.0 ](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120). Docker itself is not used to perform any of the operations done by these functions.
+`pkgs.dockerTools` is a set of functions for creating and manipulating Docker images according to the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120). Docker itself is not used to perform any of the operations done by these functions.
 
 ## buildImage {#ssec-pkgs-dockerTools-buildImage}
 
@@ -52,7 +52,7 @@ The above example will build a Docker image `redis/latest` from the given base i
 
 > **_NOTE:_** Using this parameter requires the `kvm` device to be available.
 
-- `config` is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the [ Docker Image Specification v1.2.0 ](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).
+- `config` is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions).
 
 After the new layer has been created, its closure (to which `contents`, `config` and `runAsRoot` contribute) will be copied in the layer itself. Only new dependencies that are not already in the existing layers will be copied.
 
diff --git a/doc/builders/images/snaptools.section.md b/doc/builders/images/snaptools.section.md
index 9e1403b88285..5f710d2de7fe 100644
--- a/doc/builders/images/snaptools.section.md
+++ b/doc/builders/images/snaptools.section.md
@@ -14,7 +14,7 @@ Currently, `makeSnap` does not support creating GUI stubs.
 
 The following expression packages GNU Hello as a Snapcraft snap.
 
-```{#ex-snapTools-buildSnap-hello .nix}
+``` {#ex-snapTools-buildSnap-hello .nix}
 let
   inherit (import <nixpkgs> { }) snapTools hello;
 in snapTools.makeSnap {
@@ -35,7 +35,7 @@ in snapTools.makeSnap {
 
 Graphical programs require many more integrations with the host. This example uses Firefox as an example, because it is one of the most complicated programs we could package.
 
-```{#ex-snapTools-buildSnap-firefox .nix}
+``` {#ex-snapTools-buildSnap-firefox .nix}
 let
   inherit (import <nixpkgs> { }) snapTools firefox;
 in snapTools.makeSnap {
diff --git a/doc/builders/packages/cataclysm-dda.section.md b/doc/builders/packages/cataclysm-dda.section.md
index 0f908cb75909..bfeacb47feff 100644
--- a/doc/builders/packages/cataclysm-dda.section.md
+++ b/doc/builders/packages/cataclysm-dda.section.md
@@ -1,6 +1,6 @@
 # Cataclysm: Dark Days Ahead {#cataclysm-dark-days-ahead}
 
-## How to install Cataclysm DDA
+## How to install Cataclysm DDA {#how-to-install-cataclysm-dda}
 
 To install the latest stable release of Cataclysm DDA to your profile, execute
 `nix-env -f "<nixpkgs>" -iA cataclysm-dda`. For the curses build (build
@@ -34,7 +34,7 @@ cataclysm-dda.override {
 }
 ```
 
-## Important note for overriding packages
+## Important note for overriding packages {#important-note-for-overriding-packages}
 
 After applying `overrideAttrs`, you need to fix `passthru.pkgs` and
 `passthru.withMods` attributes either manually or by using `attachPkgs`:
@@ -69,7 +69,7 @@ in
 goodExample2.withMods (_: [])    # parallel building enabled
 ```
 
-## Customizing with mods
+## Customizing with mods {#customizing-with-mods}
 
 To install Cataclysm DDA with mods of your choice, you can use `withMods`
 attribute:
diff --git a/doc/builders/packages/elm.section.md b/doc/builders/packages/elm.section.md
index 53087c0e9ded..ae223c802da4 100644
--- a/doc/builders/packages/elm.section.md
+++ b/doc/builders/packages/elm.section.md
@@ -6,6 +6,6 @@ To start a development environment do
 nix-shell -p elmPackages.elm elmPackages.elm-format
 ```
 
-To update the Elm compiler, see <filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>.
+To update the Elm compiler, see `nixpkgs/pkgs/development/compilers/elm/README.md`.
 
 To package Elm applications, [read about elm2nix](https://github.com/hercules-ci/elm2nix#elm2nix).
diff --git a/doc/builders/packages/firefox.section.md b/doc/builders/packages/firefox.section.md
index acf31e188c3e..b7c430db232d 100644
--- a/doc/builders/packages/firefox.section.md
+++ b/doc/builders/packages/firefox.section.md
@@ -1,6 +1,6 @@
 # Firefox {#sec-firefox}
 
-## Build wrapped Firefox with extensions and policies
+## Build wrapped Firefox with extensions and policies {#build-wrapped-firefox-with-extensions-and-policies}
 
 The `wrapFirefox` function allows to pass policies, preferences and extension that are available to firefox. With the help of `fetchFirefoxAddon` this allows build a firefox version that already comes with addons pre-installed:
 
diff --git a/doc/builders/packages/opengl.section.md b/doc/builders/packages/opengl.section.md
index 6866bf89221a..ee7f3af98cfc 100644
--- a/doc/builders/packages/opengl.section.md
+++ b/doc/builders/packages/opengl.section.md
@@ -4,11 +4,11 @@ OpenGL support varies depending on which hardware is used and which drivers are
 
 Broadly, we support both GL vendors: Mesa and NVIDIA.
 
-## NixOS Desktop
+## NixOS Desktop {#nixos-desktop}
 
 The NixOS desktop or other non-headless configurations are the primary target for OpenGL libraries and applications. The current solution for discovering which drivers are available is based on [libglvnd](https://gitlab.freedesktop.org/glvnd/libglvnd). `libglvnd` performs "vendor-neutral dispatch", trying a variety of techniques to find the system's GL implementation. In practice, this will be either via standard GLX for X11 users or EGL for Wayland users, and supporting either NVIDIA or Mesa extensions.
 
-## Nix on GNU/Linux
+## Nix on GNU/Linux {#nix-on-gnulinux}
 
 If you are using a non-NixOS GNU/Linux/X11 desktop with free software video drivers, consider launching OpenGL-dependent programs from Nixpkgs with Nixpkgs versions of `libglvnd` and `mesa.drivers` in `LD_LIBRARY_PATH`. For Mesa drivers, the Linux kernel version doesn't have to match nixpkgs.
 
diff --git a/doc/builders/packages/steam.section.md b/doc/builders/packages/steam.section.md
index e33f1192f7c0..d7bb6e69d7d9 100644
--- a/doc/builders/packages/steam.section.md
+++ b/doc/builders/packages/steam.section.md
@@ -20,6 +20,7 @@ Use `programs.steam.enable = true;` if you want to add steam to systemPackages a
 ## Troubleshooting {#sec-steam-troub}
 
 - **Steam fails to start. What do I do?**
+
   Try to run
 
   ```ShellSession
@@ -32,24 +33,26 @@ Use `programs.steam.enable = true;` if you want to add steam to systemPackages a
 
   - The `newStdcpp` parameter was removed since NixOS 17.09 and should not be needed anymore.
   - Steam ships statically linked with a version of libcrypto that conflics with the one dynamically loaded by radeonsi_dri.so. If you get the error
+
     ```
     steam.sh: line 713: 7842 Segmentation fault (core dumped)
     ```
+
     have a look at [this pull request](https://github.com/NixOS/nixpkgs/pull/20269).
 
 - **Java**
 
   1. There is no java in steam chrootenv by default. If you get a message like
 
-  ```
-  /home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found
-  ```
+    ```
+    /home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found
+    ```
 
-  You need to add
+    you need to add
 
-  ```nix
-  steam.override { withJava = true; };
-  ```
+    ```nix
+    steam.override { withJava = true; };
+    ```
 
 ## steam-run {#sec-steam-run}
 
@@ -57,9 +60,9 @@ The FHS-compatible chroot used for steam can also be used to run other linux gam
 
 ```nix
 pkgs.steam.override ({
-          nativeOnly = true;
-          newStdcpp = true;
-        }).run
+  nativeOnly = true;
+  newStdcpp = true;
+}).run
 ```
 
 to your configuration, rebuild, and run the game with
diff --git a/doc/builders/packages/xorg.section.md b/doc/builders/packages/xorg.section.md
index be220a25404a..ae885f923467 100644
--- a/doc/builders/packages/xorg.section.md
+++ b/doc/builders/packages/xorg.section.md
@@ -2,7 +2,7 @@
 
 The Nix expressions for the X.org packages reside in `pkgs/servers/x11/xorg/default.nix`. This file is automatically generated from lists of tarballs in an X.org release. As such it should not be modified directly; rather, you should modify the lists, the generator script or the file `pkgs/servers/x11/xorg/overrides.nix`, in which you can override or add to the derivations produced by the generator.
 
-## Katamari Tarballs
+## Katamari Tarballs {#katamari-tarballs}
 
 X.org upstream releases used to include [katamari](https://en.wiktionary.org/wiki/%E3%81%8B%E3%81%9F%E3%81%BE%E3%82%8A) releases, which included a holistic recommended version for each tarball, up until 7.7. To create a list of tarballs in a katamari release:
 
@@ -14,11 +14,11 @@ cat $(PRINT_PATH=1 nix-prefetch-url $url | tail -n 1) \
   | sort > "tarballs-$release.list"
 ```
 
-## Individual Tarballs
+## Individual Tarballs {#individual-tarballs}
 
 The upstream release process for [X11R7.8](https://x.org/wiki/Releases/7.8/) does not include a planned katamari. Instead, each component of X.org is released as its own tarball. We maintain `pkgs/servers/x11/xorg/tarballs.list` as a list of tarballs for each individual package. This list includes X.org core libraries and protocol descriptions, extra newer X11 interface libraries, like `xorg.libxcb`, and classic utilities which are largely unused but still available if needed, like `xorg.imake`.
 
-## Generating Nix Expressions
+## Generating Nix Expressions {#generating-nix-expressions}
 
 The generator is invoked as follows:
 
@@ -29,6 +29,6 @@ cd pkgs/servers/x11/xorg
 
 For each of the tarballs in the `.list` files, the script downloads it, unpacks it, and searches its `configure.ac` and `*.pc.in` files for dependencies. This information is used to generate `default.nix`. The generator caches downloaded tarballs between runs. Pay close attention to the `NOT FOUND: $NAME` messages at the end of the run, since they may indicate missing dependencies. (Some might be optional dependencies, however.)
 
-## Overriding the Generator
+## Overriding the Generator {#overriding-the-generator}
 
 If the expression for a package requires derivation attributes that the generator cannot figure out automatically (say, `patches` or a `postInstall` hook), you should modify `pkgs/servers/x11/xorg/overrides.nix`.
diff --git a/doc/builders/trivial-builders.chapter.md b/doc/builders/trivial-builders.chapter.md
index bc1317cc49c0..46620e1b459c 100644
--- a/doc/builders/trivial-builders.chapter.md
+++ b/doc/builders/trivial-builders.chapter.md
@@ -37,7 +37,7 @@ This works just like `runCommand`. The only difference is that it also provides
 
 Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network roundrip and can speed up a build.
 
-::: note
+::: {.note}
 This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr-allowSubstitutes), so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g. just copying some files to a different location or adding symlinks), because there the `system` is usually the same as `builtins.currentSystem`.
 :::
 
diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md
index 1eaa06a659d5..e42ba512b98f 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}
 
@@ -462,9 +462,9 @@ Preferred source hash type is sha256. There are several ways to get it.
 
     For package updates it is enough to change one symbol to make hash fake. For new packages, you can use `lib.fakeSha256`, `lib.fakeSha512` or any other fake hash.
 
-    This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn't applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73")). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash.
+    This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn’t applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73)). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash.
 
-::: warning
+::: {.warning}
 This method has security problems. Check below for details.
 :::
 
diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md
index 7fd4b93f0d2b..2f7ae32259c4 100644
--- a/doc/contributing/contributing-to-documentation.chapter.md
+++ b/doc/contributing/contributing-to-documentation.chapter.md
@@ -1,6 +1,6 @@
 # Contributing to this documentation {#chap-contributing}
 
-The DocBook sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository.
+The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. The manual is still partially written in DocBook but it is progressively being converted to [Markdown](#sec-contributing-markup).
 
 You can quickly check your edits with `make`:
 
@@ -22,3 +22,78 @@ $ nix-shell
 ```
 
 If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
+
+## Syntax {#sec-contributing-markup}
+
+As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
+
+Additionally, the following syntax extensions are currently used:
+
+- []{#ssec-contributing-markup-anchors}
+  Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).
+
+  It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:<