ReST is really big in the Python ecosystem, thanks to Sphinx (docs generator), and the read-the-docs website. The main advantage for ReST is that it is well de

ReST is really big in the Python ecosystem, thanks to Sphinx (docs generator), and the read-the-docs website. The main advantage for ReST is that it is well defined and consistent. It's a bit heavier than .md, but I think it will pay off for large projects. Here are some articles about it: https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/ https://eli.thegreenplace.net/2017/restructuredtext-vs-markd... http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/ http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-f... I've written docs for personal projects in markdown, but now that I work on larger collaborative projects I feel like ReST is the way to go. PS: If you're using Sphinx, you can actually support both .md and .rst in the same project, and slowly transition from one to the other, see https://github.com/ivanistheone/ricecooker/blob/docs/improve/docs/conf.py#L447 https://github.com/ivanistheone/ricecooker/blob/docs/improve...