Markup Languages

I read an article (“Living the Future of Technical Writing” by Scott Chacon) and I have some thoughts



I read an article titled “Living the Future of Technical Writing” by Scott Chacon, the author of Pro Git, and it got me thinking a little about the techical writing process, and the formats I use to markup text.

I have no personal experience with asciidoc – most of the plain-text based markup I write is in markdown or reStructuredText. I like markdown, but sometimes it’s too simple and has ambiguously defined behaviors (like pre/code text in a list item). I like reStructuredText, but some aspects of it’s syntax leave a bad taste (the weird syntax for links and no spaces before number/bullet for lists to name a couple).

And so, reading this article made me want to find out if asciidoc improves on the issues I have with markdown and reStructuredText, and what kind of tooling I can use to manipulate it.

Some neat features specific to asciidoc:

Some things I can see already annoying me:

I might give this format a serious shot – there is asciidoctor.js, so I might be able to integrate it into my Metalsmith build! I’m certainly going to test it out, but who knows if it’ll go anywhere…