I already contributed last month the Maven language support section in markdown !
It was pretty easy and I didnt even contemplate more advanced Markdown features.
A style footer that takes you the markdown file though to edit or fix would be A+ though.
I’ve always appreciated that in projects I’ve come to love.
I am having a bit of trouble getting inline docbook tags to work in markdown. pandoc seems to be stripping the tags out of the document.
Does anyone have an example of this working anywhere? I haven’t seen any documents in nixpkgs using it.
@wil Here’s an example where an inline-docbook tag worked: https://github.com/NixOS/nixpkgs/blame/2bb9e7c18a6b920074a4fe8bbbfab0e73b066c16/doc/languages-frameworks/beam.section.md#L84
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.
```{=docbook}
Put any docbook code here
``
I’ve made a Meta issue for converting from Docbook to CommonMark where we can gather up the best practices.
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.
@ryantm just a little nit that the documentation on nixpkgs itself are a bit different than the issue generated templates.
They mention entering nix-shell before doing nix-build and also running make clean
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.
Here is an example pandoc command
nix run nixpkgs.pandoc --command pandoc --from docbook \
-s doc/builders/packages/weechat.xml \
--to commonmark \
-o doc/builders/packages/weechat.section.md
Update: we’ve converted 10 sections so far and 5 more are in progress.
Special thanks to these new (since last update) conversion contributors:
@Mic92, @fzakaria, @AndersonTorres, @wil
Up to 15 conversions done; 9 in progress; and I’ve added more To Do items.
Special thanks to these new (since last update) conversion contributors:
Stupremee, @mmlb, @lucasew
Visit the CommonMark Docs project and pick a To Do issue today.
Thanks @ryantm, a great initiative.
Some parts of the documentation:
are generated with GitHub - nix-community/nixdoc: Tool to generate documentation for Nix library functions [maintainer=@infinisil]
Is there already a plan to migrate that parts?
Thanks for pointing that out, @jlesquembre! I’ve opened an issue on the nixdoc repository to discuss it.
The following sections have been converted:
The following infrastructure improvements were made:
Visit the CommonMark Docs project and pick a To Do issue today.
Opened a PR converting platform-notes. stdenv/platform-notes: convert to markdown by siraben · Pull Request #106921 · NixOS/nixpkgs · GitHub
I added it to the project. Please @ me if you open any other ones.
@ryantm Can you add this the project? Convert contributing + using section from Docbook to CommonMark · Issue #120011 · NixOS/nixpkgs · GitHub
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:
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.
Special thanks to all these people who’ve been helping convert things since my last update: @blaggacao, @bobby285271, @ngiger, @bryanasdev000, @siraben, @wayofthepie, @jtojnar.
First of all, thank you to everyone who is providing feedback and help on these efforts, we are making great progress!
You can help the DocBook to CommonMark conversion efforts by grabbing one of the new todo issues in the project!
Since the last update, I did the following:
All this work is available at doc: add nixpkgs manual split into multiple pages by ryantm · Pull Request #108063 · NixOS/nixpkgs · GitHub and there is a live demo.
Work left to do:
We’re starting to convert the NixOS manual too and you can help out by grabbing one of the new todo issues in the project!
#! /usr/bin/env nix-shell
#! nix-shell -i bash -p git meld gitAndTools.gh
set -eou pipefail
trap "kill 0" SIGINT SIGTERM EXIT
PR="$1"
gh pr checkout "$PR"
MB="$(git merge-base HEAD master)"
nix-build nixos/release.nix -A manual.x86_64-linux
CONVERTED_MAN="$(readlink result)"
git checkout master
nix-build nixos/release.nix -A manual.x86_64-linux
MB_MAN="$(readlink result)"
nix-shell -p python3 --run "python3 -m http.server 8000 --directory $MB_MAN/share/doc/nixos" &
nix-shell -p python3 --run "python3 -m http.server 8001 --directory $CONVERTED_MAN/share/doc/nixos" &
sleep 2
"$BROWSER" localhost:8000/
"$BROWSER" localhost:8001/
meld "$MB_MAN/share/doc/nixos/" "$CONVERTED_MAN/share/doc/nixos/" &
sleep 5
read -r -p "Press enter to exit."
Thank you once again for your help and support!
I just converted some articles, some are not tracked in the project yet:
https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+author%3Abobby285271+nixos%2Fdoc+is%3Aopen
Thanks in advance for reviewing 
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. 