duncanlock.net
Asciidoc
Figure 1. Asciidoc.

I’ve been using reStructuredText for writing on this blog, because it has lots of built-in features that markdown doesn’t.

However, reStructuredText’s actual syntax is a bit…​ fiddly - particularly its non-atx headings, too many things relying on lining up white space, etc…​ If I don’t use it for a bit, I have to look up or copy & paste all the advanced syntax.

I’d prefer to use AsciiDoc, as it has all the extra features, and if you use Asciidoctor, all the simple stuff is the same as markdown - which isn’t (currently) standard AsciiDoc, but is a nice simplification.

The subset of features from reStructuredText (or Asciidoc) that Markdown doesn’t have – and that I’m actually using on this blog, are:

  • Figure/Images with captions
  • Admonitions
  • Front-matter/Metadata
  • Footnotes
Read More