Asciidoctor for collaborative book writing

(Last Updated On: January 4, 2018)

I’ve been searching for the most suitable tools I’d use for my book writing process and I’ve settled for Asciidoctor.

In the first place, I decided to use a markup text language that’s implicitly supported by GitHub, and after reviewing Markdown and Asciidoc, I opted for the latter for it offers a richer syntax.

The only problem with Asciidoc is Windows. The a2x command uses xmllint, and therefore you must use Cygwin or a virtual machine with a Linux image. This is not what I aim for, and therefore I continued evaluating git-scribe.

This is a tool meant for writing ebooks, and it’s pretty cool unless you use it on Windows. After manually installing all its dependencies (ruby, asciidoc, xsltproc, source-highlight, apache fop), I somehow managed to generate a HTML book example, but the PDF generation didn’t work. The Apache FOP classes were not found, and since I’m no Ruby expert, I simply gave up and decided to try Asciidoctor.

Running on Ruby, Asciidoctor simply works like a charm. I managed to install a Ruby file watcher that automatically generates the HTML version of my markups. PDF works and the syntax doesn’t scare me a bit. There are small differences between the original AsciiDoc and the new Asciidoctor, but that’s neglectable.

Subscribe to our Newsletter

* indicates required
10 000 readers have found this blog worth following!

If you subscribe to my newsletter, you'll get:
  • A free sample of my Video Course about running Integration tests at warp-speed using Docker and tmpfs
  • 3 chapters from my book, High-Performance Java Persistence, 
  • a 10% discount coupon for my book. 
Get the most out of your persistence layer!


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.