Even with the issues of markdown, I still prefer it over restructured text. For some reason I have never liked reST. I use Sphinx[1] for documentation, and while I love it as a tool, I still dislike reST.

I would love it if Sphinx (or if there was a decent sphinx alternative) supported creole or markdown, but it is quite tightly tied to reST.

[1]: sphinx-doc.org

I feel exactly the same. For whatever reason, it seems like at every point where markdown and reST diverge, the way that I naturally want to write lines up with markdown (so I rarely have to look at the docs) and reST does something completely unintuitive (to me). So writing reST just feels like it's fighting me on every little thing while markdown almost always Just Works (for me). Sphinx and ReadTheDocs are great, but I dread having to write reST to use them.

The problem is that there is nothing that can replace rst currently. The reason Sphinx uses rst is because it's incredibly expressive and extensible. This is incredible important if you want to write good documentation.

For instance you can use `.. versionadded:: 0.2` to indicate that something was added in a specific version. The builder then render a nice and consistent block that can be styled in whatever way necessary. You can use :ref:`bar` to reference something in Sphinx, :kbd:`alt + k` to indicate a key sequence etc.

We could not have used Markdown for this without making a new dialect of Markdown. Also unlike rst Markdown is very ambiguous and restrictive. There are certain elements you can't use below others. That very, very rarely applies to rst. For instance you can without a problem have code blocks in tables or code lists in tables etc.

Ha. Good to hear I am not the only one that feels that way!