skipping heading levels (eg from # to ###, or starting at ###) is legal
in pandoc, but not in nixos-render-docs. pandoc acts as though section
levels *were* consecutive, nixos-render-docs prefers to tell people not
to do that kind of thing because it can make documents more fragile.
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.
