July 2, 2015

Stop Using Markdown

Markdown has become the de facto standard for plain text syntax. It’s supported in the webform editors of StackOverflow, Github, and …​. It’s build into most static site generators. You can even use it to write a book. It’s fantastic that it has raised awareness of text-based markup, but it’s not enough.

Markdown Shortcomings

You’re probably aware of most of these, but maybe don’t notice the pain as much as you should.

Comments

Definition lists

Too much HTML

Asciidoc is much richer, and not significantly harder to learn.

Markdown-to-Asciidoc Conversion Guide