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.

1 files changed, 3 insertions, 1 deletions

diff --git a/doc/languages-frameworks/crystal.section.md b/doc/languages-frameworks/crystal.section.md
index 74790132974ad..cbe31f9f0b2fc 100644
--- a/doc/languages-frameworks/crystal.section.md
+++ b/doc/languages-frameworks/crystal.section.md
@@ -1,10 +1,11 @@
 # Crystal {#crystal}
 
-## Building a Crystal package
+## Building a Crystal package {#building-a-crystal-package}
 
 This section uses [Mint](https://github.com/mint-lang/mint) as an example for how to build a Crystal package.
 
 If the Crystal project has any dependencies, the first step is to get a `shards.nix` file encoding those. Get a copy of the project and go to its root directory such that its `shard.lock` file is in the current directory, then run `crystal2nix` in it
+
 ```bash
 $ git clone https://github.com/mint-lang/mint
 $ cd mint
@@ -15,6 +16,7 @@ $ nix-shell -p crystal2nix --run crystal2nix
 This should have generated a `shards.nix` file.
 
 Next create a Nix file for your derivation and use `pkgs.crystal.buildCrystalPackage` as follows:
+
 ```nix
 with import <nixpkgs> {};
 crystal.buildCrystalPackage rec {