Finding the right toolchain to work on open documents

The source of this document (written is asciiDoc) is available on Github.
The pdf, html and slide versions of this document are also on Github.

The goal

I’d like to be able to write my courses and tutorials in one document, then convert them to slides / pdfs / ebooks / web pages at the click of a button.
On a second button click, I’d like these docs to be uploaded on the web to make them open access, versionable and fit for multi-authoring.


Figure 1. A diagram showing the authoring steps to create open, web friendly docs

In the previous blog post, I presented asciidoc as a promising technology to create easily open courses and tutorials.
It allows to write clean, minimum text files which then convert to web pages, pdf, ebooks and slides at a click of a button.

Just like you can write Word documents in MS Word or in Open Office, many tools exist to work on asciidoc.
I am still trying to figure out which one would best fit my needs. Because I program in Java, I looked at Java-based solutions because I can more easily adapt them to my needs.


I tried first AsciiDocFX, based on the emerging JavaFX technology. You can install it easily for Mac, Windows and Linux. Try it!
The great part is that you have an instant preview in html or slides, as you type.

Remember I want to embed pics and diagrams from Google Drawings into my docs? These pics have weird links like:
which are not processed easily by AsciiDocFX.

A workaround is to first download the content of the web link as a file, then embed this file into the asciidoc.
I could not figure how to manage this from AsciiDocFX. It made me fear that AsciidocFX was too hard to customize, so I searched for a more flexible solution.


This is another Java version of the tools used to convert an asciidoc into web pages, pdf and the rest.
AsciiDocJ is not a software you install, this is a programming tool to be used in a programming environment.

  • I can use it from NetBeans, which is my favorite programming editor
  • Much less user friendly than AsciiDocFX (no preview of your docs), but I could live with that.
  • Provides full flexibility to manipulate the documents, by using code.

Web based pics can’t be embedded in my doc?
No problem, I can write some additional code which scans my doc, finds these web links and apply the necessary steps to make them right.
I am more confident that other bumps on the road of processing the conversion of docs (footnotes in books? transitions in slides? custom styling?) can be dealt with.

Next steps

AsciiDocJ is configured through Maven rather than in pure java code. Maven is a protocol written in Java to customize the assembly of the files of a project: zipping them, sending them to a server, executing them…
The trick is, Maven is configured through a quite complex XML file. I need some time to get acquainted to that.
If you read this post in html, slides, or pdf form this means I’ve made some progresses!


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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s