If anyone else runs into trouble with docbook tags being stripped like I did there is a work around.
You can escape any docbook code and have pandoc put it directly into the resulting document by putting it inside a code fence with this attribute on it.
Just a few tips for the people that is contributing.
Use github codespaces if possible to edit the files. It downloads the repo (~1.3GB) way faster than your home internet. Especially if you are from Brazil.
To test locally you can commit in your branch at your fork and push it, you can then download the tarball of the revision that will be way smaller than the whole repo. The url seems like https://github.com/username/nixpkgs/archive/codespaces-1.tar.gz. Untar it and do the nix-build inside the docs folder to test if its nice. You can also install a extension for markdown preview in the codespaces for better feedback loop.
If you are a vim fan, or even a normal user, you can save time replacing common tags to the markdown equivalents like <para> that just go away, <literal> that encloses with backticks and programlisting that is enclosed by backticks. The hard work is to normalize the unnumbered lists, indentation, the special symbols using &something; and wrapping <prompt>s into three backticks (because of the special symbols).
I converted <prompt> blocks into three backticks but without specifying language and converted <programlisting> into the language its written, that is mostly Nix.
For those that really want to contribute, many of them can be likely done with a pandoc conversion however please read over the generated markdown to make sure it’s good.
It has been a while since I’ve done an update but I’m pleased to announce we are very close eradicating Docbook from the nixpkgs manual!
There are only four main things left to do:
Convert a few more sections in doc/functions. I’ve added issue cards for this on the conversion project. They have detailed instructions, so they should be good first issues for people interested.
Convert the auto-generated nix library function documentation output from Docbook to CommonMark.
Convert the top-level to CommonMark and stop using the CommonMark to Docbook translation layer (that is, pick a CommonMark rendering tool).
Update NixOS website to work with new rendering system.
NixOS manual
There’s also some exciting news here. We’ve merged nixos/doc: add md-to-db.sh, which allows us to start converting the NixOS manual to CommonMark without adding pandoc/GHC to the NixOS build closure. I’ve converted some sections, and I’ll try to start adding some project issues with step-by-step instructions for doing the conversion soon.
UPD: most articles in nixos/doc/manual/administration, nixos/doc/manual/configuration, nixos/doc/manual/development, nixos/doc/manual/installation are converted now, except those have <xi:include> included. Not planing to open new PRs in a short period unless there are new todo issues.