Starting the AsciiDoc Specification Journey

by Sarah White and Dan Allen -

After numerous calls for an AsciiDoc specification over the past year, it’s abundantly clear the community is ready for AsciiDoc to take this step. We agree. We also reached out to Stuart, the originator of AsciiDoc, and we have his support as well. So now’s the perfect time to pursue it.

A new home at the Eclipse Foundation

We want AsciiDoc to have a strong future and the resources it needs to evolve and grow. To achieve this, we’ve decided to submit a proposal for an AsciiDoc language specification to the Eclipse Foundation. The Eclipse Foundation provides a home for developing specifications and is committed to transparency and open source, values that align well with AsciiDoc and its community. The Eclipse Foundation Specification Process (EFSP) provides a clear, yet customizable structure that reduces the risk of the process stalling and ensures the outcome will be usable in the real world. The process is public, vendor neutral, and all source materials and final artifacts are open source.

What will it mean for AsciiDoc to become a specification?

The specification for the AsciiDoc language will include an open source specification document, which defines required and optional API definitions, semantic behaviors, data formats, and protocols, as well as an open source Technology Compatibility Kit (TCK) that developers can use to develop and test compatible implementations. (Those of you who know Dan and I from before Asciidoctor know that an open source TCK is a hard requirement for us). A compatible implementation, as defined by the EFSP, must fully implement all non-optional elements of a specification version, must fulfill all the requirements of the corresponding TCK, and must not alter the specified API.

For users and developers alike, the AsciiDoc specification will mean a clear, working definition of what AsciiDoc is and how it should be interpreted. Developers will be able to build implementations, tools, and services around AsciiDoc without risk of diluting its meaning or splintering it. In turn, users will have more options, greater document portability, and the assurance that compatible implementations and tools will handle their AsciiDoc documents according to a versioned specification.

What will happen to Asciidoctor?

We plan to make Asciidoctor (the RubyGem) an independent, compatible implementation of AsciiDoc (the specification). (That doesn’t mean Asciidoctor as a whole is moving to the Eclipse Foundation). This may mean adding, removing, or changing features in Asciidoctor to meet the specification’s required and optional elements in order to pass the TCK. The Asciidoctor.js and AsciidoctorJ projects, if they choose, may also decide to become independent, compatible implementations with far greater freedom than before. And it will give space for emerging implementations to bring AsciiDoc to even more platforms.

We’ll know more—​and keep you updated on what to expect—​once the specification process gets under way.

Ready? Set. Spec!

The next step in creating the AsciiDoc specification is to propose it as a specification project to the Eclipse Foundation. The proposal, which Dan and I (as OpenDevise, on behalf of Asciidoctor) plan to submit, will be reviewed by the Eclipse Management Organization, then posted for community review and comment. To learn more about the specification process, I encourage you to check out Wayne Beaton’s posts Part II: The EFSP and Part III: Creation. The specification process is a fork of the Eclipse Development Process, which you can read about in Part I: The EDP. You can also read the EFSP documentation.

With a specification process that can be adapted to suit the needs of the AsciiDoc community, Dan and I believe the language will evolve in a sustainable and substantive manner that keeps pace with the community’s needs, now and into the future. We’re really excited to get started, and we hope you’ll join us on this journey to make AsciiDoc a specification!

Wow! AsciiDoc is incredible!! I’m impressed! (2012)

by Dan Allen -

As you may have heard, Google+ is sinking into the sea. Sadly, it’s going to take with it the post I made when I first discovered AsciiDoc…​where it all began. My interest in AsciiDoc, and even the origin of Asciidoctor, can be traced back to this post. So we don’t lose this bit of history, I’ve decided to preserve it here on the Asciidoctor blog. Keep in mind that some of the references in this post are outdated.

The Google+ Post

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!

If you are interested in using it to write a book, see 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:

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:

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.

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. See

Post Activity








Henry Lee +1’d, Milan Navrátil +1’d, Ravishankar Haranath +1’d, Markus C +1’d, Chris Drew +1’d, csgeek reshared, Andrey “Bass” Shcheglov +1’d, Gavin Engel +1’d, Марк Сафронов +1’d and reshared, Liam OBrien +1’d, Anatoly Yakubov +1’d, Mhd Shulhan +1’d, Kartik Singhal +1’d, Ahmad Khayyat +1’d, Benjamin Kampmann reshared, Kevin Retzke +1’d, 张文涛 +1’d and reshared, Shane Weng reshared, Alex Sherlock reshared, Sascha Lüdecke +1’d, Jonathan Bullock +1’d, Sten Aksel Heien reshared, Paulo Jerônimo +1’d, Anthonny Querouil reshared, Dave Campbell reshared, Leif Gruenwoldt +1’d and reshared, Søren Jones +1’d, Edmund Haselwanter +1’d, John Zoidberg +1’d, Ophir Radnitz +1’d, Italo Penna +1’d and reshared, Peti Koch reshared, Daniel Faust +1’d, cesare cugnasco +1’d, Tong Sun reshared, Jason Lee +1’d, Ding-Yi Chen +1’d, Aditya Raj Bhatt +1’d, sebastien rey coyrehourcq reshared, Martin Pool +1’d, Thomas McDermott +1’d and reshared, Easytouch reshared, Stéphane Gourichon reshared, Günter Zöchbauer +1’d, Timo Ollech +1’d, Antoni Silvestre Padrós +1’d, Dmitry Afanasiev +1’d and reshared, William Chambers reshared, Mani B +1’d, Anton Leontiev reshared, Fabricio Godoy +1’d, Gianluca Scacco reshared, Jeffrey Cardona +1’d, Brian Leathem +1’d, Samuel Bancal reshared, Jose Torres +1’d, Sebastian Peters +1’d, Ștefan Suciu +1’d, Roman Frołow +1’d and reshared, John Jelinek +1’d, Holger Joest reshared, Agam Brahma +1’d, Too simple, Sometimes naive +1’d, Jared Morgan +1’d, DeWitt Clinton +1’d, Alexander Zobkov +1’d

  • 1 of 1