Wow! AsciiDoc is incredible!! I'm impressed!

I now consider myself well-versed in AsciiDoc after spending two days converting several full-length technical tutorials to AsciiDoc and really digging deep into its capabilities.

AsciiDoc is a lightweight, yet powerful markup language that's got it all:

- It's readable
- It's comprehensive
- It's extensible
- It produces beautiful output (in HTML, DocBook, PDF, ePub and more)

Now this is a lightweight markup language worthy of producing a book!

Tip: If you are interested in using it to write a book, see git-scribe: https://github.com/schacon/git-scribe

Think of it this way:

If Markdown is a 1st-grader, then AsciiDoc is PhD student.

For basic formatting, Markdown and AsciiDoc look remarkably similar, making AsciiDoc a drop-in, no-brainer replacement to Markdown (both in terms of simplicity and straightforward migration). Yet, the AsciiDoc syntax seems to continue on with no end. In fact, there is no end since it can be extended (and tweaked) rather easily.

What about Docbook? Ah! The great thing about AsciiDoc is that you can still produce Docbook without any of the pain or without sacrificing any features. Perhaps AsciiDoc should adopt this slogan:

Writing in Docbook is just, inhumane.

I could list all features AsciiDoc supports, but a showcase speaks for itself: http://powerman.name/doc/asciidoc

Getting back to my experiment....

I had the opportunity to seriously evaluate and contrast the serious lightweight markup languages: reStructuredText (and its complement Sphinx), Textile and AsciiDoc. Hands down, AsciiDoc is the winner. If there's such a thing as a sure thing in software, AsciiDoc is it.

I first converted a full-length technical tutorial into reStructuredText. It took roughly 3 hours to struggle through the syntax and get it converted, with holes still remaining here and there. The syntax is just quirky (what's the obsession with backticks and colons?) and hard to commit to memory. On the whole, it just leaves a bad taste. I was pretty deflated and ready to throw in the towel.

On my way to bed, a hint of curiosity motivated me to give AsciiDoc a shot. Within 15 minutes I had converted the whole document. Plus, I had outputs in HTML, PDF, plain text, ePub and Docbook to show for it. I was even starting to play with additional formatting and organization features. I felt like I found the holy grail of documentation.

Here's the result of that experiment:

Source
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.asciidoc

Conf
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.conf

HTML
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.html

PDF
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.pdf

Documentation can be easy and fun. Who would have thought?

I'm about as excited about AsciiDoc as I am about git (and the combination is just bliss). And there's still so much to explore. I definitely encourage you to check it out. AsciiDoc is even supported as a markup format on github (and gists), making it easy to get started.

Tip: If you're on Fedora, download the latest version of AsciiDoc from the website rather than install the RPM. The RPM is missing files from the distribution.

Update (2014-08-15): Since this post is often referenced for information about AsciiDoc, I'm updating it to point to a more recent AsciiDoc cheatsheet.

http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/