I think the reasons for overlooking reStructuredText are overstated. Markdown is not unavoidable. I'm a fairly experienced programmer (Django core committer, and develop the full stack from SQL through to Javascript), and though I barely know Markdown, I really don't feel like I'm missing much. For example, on GitHub: name your README as README.rst and it will be parsed as reStructuredText. The fact that GitHub uses markdown for comments it no big deal really - I use GitHub and hadn't noticed that it was Markdown, because the amount of markup you need on something like GitHub is actually pretty minimal. I think that that is Markdown's sweet spot - really simple stuff, where you don't actually know that you are using it, and it's not that important to know the rules. Once you get beyond that, and actually need a formal spec, I think it is foolish to try to use Markdown, because it wasn't designed for that. Rather, you want something more stable and predictable, and also extensible, like reStructuredText. reStructuredText is also very popular in the Python world - almost all new documentation uses it (using Sphinx), which is made possible by its extensibility. reStructuredText also has multiple highly compatible implementations (Python's docutils and Haskell's Pandoc, perhaps others).