[ivansavz]

It's interesting that they mix markdown and restructured text. ReST is clearly the superior formatting language, but markdown is so much easier to pick up and use.

[johnhenry]

Just curious, I've never actually heard of "ReST" as a format before now... I wonder if you might be able to explain what makes it superior to markdown?

[ivansavz]

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-markd... 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...

[accordionclown]

rest (restructured text) has been used for python documentation for a very long time. so -- especially for that particular usage -- it's much more functional and clearly documented and consistent and free of edge-cases than (the far-too-numerous flavors of) markdown.

on the negative side, there aren't many quality authoring-tools for rest.

markdown has a very high profile. but it's questionable whether it deserves it. (i wouldn't say that it doesn't. but i wouldn't say that it does, either.)

another option you could look at is asciidoc. it isn't clearly better or worse than those other two systems, but it is different, and you might end up liking it better. (or you might not.)

light-markup systems are much like static blog systems. there's a lot of them, but it's hard to decide among them, and many people end up inventing their own variant that serves their own individual use-cases.