Creating an eBook using the AsciiDoc markup language

No readers like this yet.
paper planes

For manuals and guides, Wikis are an excellent way of organizing content. Yet, they often don't work as well for larger articles or books because individual content is spread across many pages and the reader has to click around. Additionally, when you want to read online content while in a place where you cannot get an Internet connection (like, reading on the plane), another mode of content delivery is needed.

Recently, I was quite thrilled to see offer a thorough and skillful way of How to create an eBook the open source way. But, I am not a big fan of Wysiwig editors and prefer markup languages like LaTeX, Markdown, AsciiDoc, or even Wiki-Markup. So, here I give you an alternative: preparing content for an eBook editing AsciiDoc documents. [You can also do this on the go, in an email editor on your mobile phone or tablet.]


AsciiDoc is a markup language that has been around for quite some time. The content is created in plain text and is readable in its source form. For instance:

 = Chapter 1

The quick brown fox jumps over the source `code`

image::myCat.png[A lolcat]


* First list item

* Second list item

* Third list item


= Chapter 2

Lorem ipsum...


Note: This is a simple example; AsciiDoc formatting can be much more powerful.

Processing AsciiDoc

A tool chain written in Python is available to transform documents in target formats like .html, .pdf, and also ePub. To convert a document written in AsciiDoc, run the command like this:

asciidoc -d book  <input.adoc>

And the load the resulting .html document in your browser.

Using asciidoctor instead of AsciiDoc for processing

Asciidoctor is a drop-in replacement for the AsciiDoc command. There are some small differences, but typically they do not make a difference. Asciidoctor is writen in Ruby and is notably faster. Get it via gem install asciidoctor, then use it similar to the above:

asciidoctor -d book  <input.adoc>

Use autoload extensions in the browser for live preview

Manually switching between text editor, command line and browser to get a preview is still a bit cumbersome, so Dan Allen has described a way to automatically trigger a recreation of the output document when the file has changed. On top of that, a browser plugin can then detect the changed .html file and automatically reload it. If you keep browser window and editor next to each other you basically have wysiwyg editing.

Turning the document into ePub

Now that the document is finished we can render it in ePub format. For this we will use AsciiDoc and its tool chain, especially the a2x command.

a2x -fepub -d book <input.adoc>

First, this internally converts the document to a docbook, and from there, into the final ePub. This process is mostly transparent to the user except in cases where the original document violates some of the rules of ePub and a2x returns a cryptic error message. The documentation has an extended guide on how to use a2x to create ebooks with AsciiDoc.

User profile image.
Heiko is a long time open source committer. He currently works for Red Hat on the topic of monitoring and management of server and softwares systems. Heiko has received a master in Computer Science from University of Karlsruhe and has written two books on JBoss AS and Enterprise Java Beans.


Thanks for this article. It's been a while since I've used AsciiDoc, and this was a good reminder of what it can do.

One question: how well do the books generated with AsciiDoc validate using a tool like epubcheck?

I didn't mention epubcheck for brevity of the article. When I last converted a longer text the a2x tool itself was complaining about issues, which turned out to be typographical " that sneaked in from copy&pasting a text from a Word processor. After that was solved all went smooth and epubcheck then complained about what it thinks to be a non-registered uri scheme (irc:// ) in my text, but that is all.

Thanks for the information. Good to know that EPUBs generated with AsciiDoc validate. I might just have to give AsciiDoc another look. I think I have an ebook project that might be perfect for it ...

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License.