doc: prepare for commonmark

We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.

Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist

While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.

4 files changed, 10 insertions, 5 deletions

diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md
index 1eaa06a659d..4fa88895484 100644
--- a/doc/contributing/coding-conventions.chapter.md
+++ b/doc/contributing/coding-conventions.chapter.md
@@ -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 05b00d9bdda..44feac7fbf7 100644
--- a/doc/contributing/contributing-to-documentation.chapter.md
+++ b/doc/contributing/contributing-to-documentation.chapter.md
@@ -25,7 +25,7 @@ If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.
 
 ## Syntax {#sec-contributing-markup}
 
-As per [RFC 0062](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
+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:
 
diff --git a/doc/contributing/reviewing-contributions.chapter.md b/doc/contributing/reviewing-contributions.chapter.md
index 0dfe22199c6..3f3ba60947c 100644
--- a/doc/contributing/reviewing-contributions.chapter.md
+++ b/doc/contributing/reviewing-contributions.chapter.md
@@ -1,6 +1,6 @@
 # Reviewing contributions {#chap-reviewing-contributions}
 
-::: warning
+::: {.warning}
 The following section is a draft, and the policy for reviewing is still being discussed in issues such as [#11166](https://github.com/NixOS/nixpkgs/issues/11166) and [#20836](https://github.com/NixOS/nixpkgs/issues/20836).
 :::
 
@@ -35,15 +35,18 @@ Reviewing process:
 - Building the package locally.
   - pull requests are often targeted to the master or staging branch, and building the pull request locally when it is submitted can trigger many source builds.
   - It is possible to rebase the changes on nixos-unstable or nixpkgs-unstable for easier review by running the following commands from a nixpkgs clone.
+
     ```ShellSession
     $ git fetch origin nixos-unstable
     $ git fetch origin pull/PRNUMBER/head
     $ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD
     ```
+
     - The first command fetches the nixos-unstable branch.
     - The second command fetches the pull request changes, `PRNUMBER` is the number at the end of the pull request title and `BASEBRANCH` the base branch of the pull request.
     - The third command rebases the pull request changes to the nixos-unstable branch.
   - The [nixpkgs-review](https://github.com/Mic92/nixpkgs-review) tool can be used to review a pull request content in a single command. `PRNUMBER` should be replaced by the number at the end of the pull request title. You can also provide the full github pull request url.
+
     ```ShellSession
     $ nix-shell -p nixpkgs-review --run "nixpkgs-review pr PRNUMBER"
     ```
diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md
index 0a465020092..97b32c15df1 100644
--- a/doc/contributing/submitting-changes.chapter.md
+++ b/doc/contributing/submitting-changes.chapter.md
@@ -71,6 +71,7 @@ Security fixes are submitted in the same way as other changes and thus the same
 - If a new version fixing the vulnerability has been released, update the package;
 - If the security fix comes in the form of a patch and a CVE is available, then add the patch to the Nixpkgs tree, and apply it to the package.
   The name of the patch should be the CVE identifier, so e.g. `CVE-2019-13636.patch`; If a patch is fetched the name needs to be set as well, e.g.:
+
   ```nix
   (fetchpatch {
     name = "CVE-2019-11068.patch";
@@ -89,7 +90,7 @@ There is currently no policy when to remove a package.
 
 Before removing a package, one should try to find a new maintainer or fix smaller issues first.
 
-### Steps to remove a package from Nixpkgs
+### Steps to remove a package from Nixpkgs {#steps-to-remove-a-package-from-nixpkgs}
 
 We use jbidwatcher as an example for a discontinued project here.
 
@@ -100,6 +101,7 @@ We use jbidwatcher as an example for a discontinued project here.
 1. Add an alias for the package name in `pkgs/top-level/aliases.nix` (There is also `pkgs/misc/vim-plugins/aliases.nix`. Package sets typically do not have aliases, so we can't add them there.)
 
     For example in this case:
+
     ```
     jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15
     ```