I've been using Asciidoc ever since I discovered it and use it a lot to be my defacto README text file. It's readable in text and it can output all kinds of other formats, like man pages, pdf, html, etc.

Lately I've been seeing more and more FLOSS projects using markdown. It's slick as far as I can tell, but it still feels far more limited then Asciidoc. Even github seems to support .md better then asciidoc. Am I missing something? Is there a reason so many people are using .md?

I would think the portability of asciidoc and one text file to bind them all makes it much more powerful.

If anyone has any insights, or can tell my why markdown (MD) is so amazing, I'll buy you a virtual beer.

  • 2
    I'll add a comment I've essentially decided to flip over to markdown these days. It seems like everything supports markdown these days. Also there are tools like pandoc which allows me to convert markdown to pdf, latex, doc, asciidoc, and essentially every format I can think of. The main reason I loved asciidoc was because I could write once and forget. It seems to be that Markdown has gained the same advantages, not to mention it has several editors like Erato for example that gives you real time previews. Just my 2 cents, revisiting this question after a reprieve.
    – csgeek
    Nov 8, 2014 at 23:44
  • This question was asked in 2013. In 2024, the answer is probably ubiquity. Especially Pandoc reader support, that's hard to beat. Feb 19 at 22:52

3 Answers 3


Markdown is a TREND. There is no reason to switch to markdown if you're satisfied and confortable with asciidoc. Markdown is fragmented and quite limited in comparison to other markup languages such as asciidoc, txt2tags or reStructuredText.


Markdown has some critical mass, and the grammar is smaller than that of Asciidoc.

Markdown does have the drawback that if you want something more complicated you're out of luck, or into implementation-specific syntax that may not fit well whereas Asciidoc can scale up.

There is a g+ post by Dan Allen comparing them and prefering Asciidoc.


Ubiquitous usage of Markdown would be its greatest strength. Markdown is supported in Github, Reddit, WhatsApp, Viber etc.

A lot of editors support Makrdown as Atom ReText and Emacs.

The syntax of Markdown is smaller than Asciidoc, Makrdown is basically headers, bold, italics, numbered list, bulleted list, links, inline code and code block. This finiteness has its appeal as one can confidently declare that they know EVERY COMMAND in Markdown.

Markdown flavours eg R Markdown, MultiMarkdown, Common Markdown offer functionality that's close to Asciidoc but, they are not compatible and not widely supported.


You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .