The main benefit of Markdown is its simplicity and intuitivness, it is based on email behavior. There are certainly way better systems, such as reST. The probl

The main benefit of Markdown is its simplicity and intuitivness, it is based on email behavior. There are certainly way better systems, such as reST. The problem is that reST is way harder to learn and less forgiving then markdown. I used python Sphynx for project docs and recently moved to mkdocs. With enough customization[^1], I would say that experience is almost identical. The one thing I like more about Sphynx is that you don't need to depend on document locations on file system, and as a older platform it has much better plugins. On the other hand markdown is everywhere now, IT people usualy know it and non-IT people can learn it too, which is valuable in many domains - for example I ask my BA to write functional specification in markdown and PlantUML so that it can be put in a feature branch along with other code, so devs can follow how it progress withs diffs etc. rather then having one big Word file which is typical otherwise. [^1] Here is what I use: https://github.com/majkinetor/mm-docs https://github.com/majkinetor/mm-docs