AsciiDoc – A friendly authoring format

I recently learned about AsciiDoc, a powerful yet intuitive, human readable and writable format for authoring books and similar kinds of structured documents:

  • Solid technology, first created in 2002
  • Plain-text format, requires no special editor
  • Cleanly separates document structure from layout details
  • Available for the JVM community since 2013
  • Simple and intuitive like Markdown
  • As powerful as DocBook, without the XML clutter
  • Syntax highlighting in vim and other editors
  • Generates DocBook, HTML, epub, PDF, …
  • AsciiDoctor toolkit generates HTML 5, DocBook 4.5
  • Renders inline on github (like markdown)
  • Maven and Gradle plugins for automation
  • Support for creating diagrams using plain-text
  • Happily used by teams at Redhat, Git, Spring, …

For example, the whole documentation for the JEE standard CDI is maintained in AsciiDoc and hosted on github as maven buildable projects.

Dan Allen, a known name in the JEE community and AsciiDoctor lead developer, says that AsciiDoc supports “the creation of reusable, human-readable, semantic content” so that we can better adapt to adaptive content and address the challenges of an electronic multi-device, multi-format world that is redefining what “book” means.

An authoring revolution?

As an author-friendly plain-text format AsciiDoc might become a catalyst in an ongoing electronic authoring revolution that treats book writing like software development with authors working directly on the book’s “source code” in git repositories, while rendering into various target formats is done using build automation tools and fast scriptable converters like AsciiDoctor.

The tech-savvy publishing house O’Reilly seems to be on the forefront of this trend and


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s