Getting started with Asciidoctor

One of the best ways to get started with AsciiDoc is to use the Asciidoctor toolchain, and specifically the Gradle integration. Ironically, the documentation on how to do this is not always clear, so this blog is an attempt to make things a bit easier.

To get started with AsciiDoc and Gradle, we’ll create a new Gradle project, add the AsciiDoc support, and then create a small demo page to get you started. So, open a Terminal, and type the following commands:

The above will create a new empty Gradle project. Now, open the build.gradle to add the required configuration for AsciiDoc.

The last thing we’ll have to do now is to create an intial document, and you’re ready to go. The default source document used by AsciiDoc is src/docs/asciidoc, so let’s create that directory:

Then, create a file in that directory. The extensions .ad, .asciidoc and .adoc are supported, where .adoc is the most widely used. I choose the file ‘test.adoc’:

If you now run the AsciiDoc Gradle task, by executing the wrapper script: ./gradlew asciidoc, then a beautiful AsciiDoc HTML file called test.html should end up in build/asciidoc/html5.

Getting started with AsciiDoctor

Converting Markdown to AsciiDoc

AsciiDoc is a fantastic format when writing blogs, books, general documentation or many other usecases. However, you’ve invested a lot of time in writing Markdown documentation, and while you understand the benefits of AsciiDoc, you’re not looking forward to rewrite all your documentation to AsciiDoc. We understand that. So, in order to automate this process, we have created a Markdown to AsciiDoc converter.

The converter was actually created as part of the IntelliJ AsciiDoc plugin, to allow conversion of Markdown documents into AsciiDoc at the press of a button. And it works great. It works actually so great that we’ve used it to convert all the documentation of Geb, a fantastic framework for browser automation, from Markdown to AsciiDoc. The conversion process took less than a second, and manually checking resulted in a couple of minor issues, all of which have been fixed in the converter.

In short, there’s really not much of a reason to stick to Markdown. AsciiDoc provides superior syntax, table support, EPub and PDF support and handles multipages extremely well. So, if you are interested, checkout the documentation and get started right away!