But these are all minor annoying details of either. The win of ReST is standardized extensions for anything. The win of Markdown is there's half an implementation running anywhere.
This is `a footnote`_? Seriously?
.. _a footnote: http://example.com/
"When comparing the markup formats for the purposes of kernel documentation, only the table support, which is much needed for the media subsystem documentation in particular, was clearly identified as being superior in AsciiDoc. Otherwise, the markup comparison was rather dispassionate; it really boiled down to the tools themselves...
... In the kernel tree, there are no tools written in Ruby, but there are plenty of tools written in Python. It was fairly easy to lean towards Sphinx in this regard."
As I read it, Asciidoctor is still superior, but their decision was to go with something written in Python that they could adapt for these specific needs.
If I was writing a technical book, I'd probably use ReST.
But, 99.9% of the time, my needs are much more mundane and fit well within the limitations of Markdown. Usually I can just sit down and write Markdown, sometimes I need to bring up a cheatsheet. When I just need to add some documentation related to my work, Markdown is perfect.
What I'd really like is something where I can write Markdown, but if I run into needing something it can't do then switch over to ReST. Because of the overlap, that seems like it should be doable. I was looking at some static site generators that might do that, but I had limited time to evaluate them and couldn't get my existing ReST documents directly to render there so I had to get back to work.
If anyone has had any success with that, I'd love to hear about it.
Oh, that and a way to see the results without having to render and load the results (which currently involves mercurial, fabric, sphinx, and a browser for me). I don't need WYSIWIG, but a quick render would be nice.
Yet for me reST is a clear winner, because it's extensible; it's relatively easy to a) write your own directives, substitution directives, and text roles and b) hook into the parser. For example, in my workflow I only use their parser with a few of my own extensions and only to get the parsed text as XML; once I got this, I continue with XSLT to transform it into what I need. (I use Python and lxml with my own extensions to XSLT as well, so I can, for example, manipulate files and update a whole directory tree right from XSLT.)
I think most of these tools would benefit if their parser was a separate component that could save the resulting tree into XML. (It would be ideal to have a configurable parser where you can tinker with the grammar.)
As soon as I finished it, I quickly realized that lobbying for its adoption and supporting it would be painful, but you might find it interesting.
And, you might say, "But I've never heard of MultiMarkdown," but the reality is that if you've used Markdown for creating, well, tables, footnotes or citations, or used a YAML metadata block for a Jekyll blog, or any number of things that weren't in the original Markdown spec but that people in practice do all the time, then you've used something that was either influenced by MultiMarkdown or something that MultiMarkdown adapted.
And that last point is larger than MultiMarkdown, specifically. I'd argue that Markdown as commonly implemented and used can do an awful lot of things that are necessary for technical documentation work. This isn't to say that ReST or AsciiDoc aren't more powerful, but in practice, there's very little I've had to write that can't be written in (Multi)Markdown.
A lightweight markup language is designed to for the user to quickly write something, and most of them have been designed with the goal of having programmers document their work without having to learn a complicated tool. If you need to write extensions for a lightweight markup language, you're using it wrong.
For anything more than that, I'd use something designed for technical documentation (DITA and DocBook come to mind).
Lightweight markup languages seem easy, and, in the beginning they are, but over time, as revisions pile up and more people work on it and you find you have more requirements than you thought you had, they become a huge hassle. You spend more time fiddling than writing. There's a reason professional writers tend to use richer tools - they make their jobs easier and they make the result better.
A particular issue I have with markdown is the bold/italic issue. However this is probably indicative of a broader issue. Markdown either does not have, or does not commonly make users aware of, an escape character which will always invoke a control-word boundary and which will never be rendered in the final text.
I've also often had different websites variations on features fail when they are nested (sometimes at all).