Yeah markdown has a great advantage that it is already widely used. Meaning more people (as in including non-developers) would have a lower barrier of entry to contributing to documentation, so hopefully less people turn away from nix from being too hard to use/understand.
danbst, with regards to machine-processability, one of the reasons I think markdown has seen success in many websites (such as github, discourse etc) is the commonmark project. Before commonmark, markdown rendering was always inconsistent depending on the website due to the original 2004 markdown ‘spec’ leaving many ambiguities to be dealt with by the parsing implementer. These days for example github and commonmark have switched to commonmark or commonmark-based markdown:
- A formal spec for GitHub Flavored Markdown - The GitHub Blog
- GitHub Flavored Markdown Spec
- Discourse CommonMark migration plans 🎊 🎈 - dev - Discourse Meta
So using a commonmark markdown implementation (and there’s probably one for your language) means compatible machine processability with github’s markdown rendering. (And in general just a very well thought out specification.)