Using AsciiDoc with IntelliJ IDEA

AsciiDoc is gaining more and more popularity compared to the competing markup languages like Markdown, yet one of the biggest complaints heard was that tooling support was inadequate. These days, however, support for AsciiDoc is available in popular editors like Atom, Sublime, Emacs, Vim, etc, and also in the most popular Java IDE, IntelliJ IDEA. This blogpost describes how to effectively use the plugin.


Installation of the plugin is easy. You can use the plugin browser (Preferences -> Plugins -> Browse repositories) and type asciidoc in the search. Alternatively, you can also open a file with an extension recognised by the AsciiDoc plugin (.adoc, .asciidoc and .ad). This will trigger an info message by IntelliJ informing you that there’s a plugin to handle these filetypes.


Live preview
Once the plugin has been installed, one of the nicest features of the plugin is that Live Preview works. It’s a little bit cumbersome to setup at the moment, but it’s worth it. To enable live preview, you first need to open an AsciiDoc document. When a file is open in the active editor, go to Window -> Editor Tabs -> Split Vertically. This will open the same document twice. Now, click on the Preview tab at the bottom of the editor in either the left or right editor. Now you’ve set up Live Preview! Making changes to the text in one editor will now be reflected in the preview.

Syntax highlighting
Basic syntax highlighting is now supported by the plugin. For example, code blocks are highlighted, as well as titles, which makes editing documents a bit more easier and it gives immediate feedback if the syntax used is correct.

The toolbar is an incubating feature of the plugin, and provides easy access to often used shortcuts, like basic formatting, but also for creating tables.

Converting from Markdown
One of the unique features of the AsciiDoc plugin is to be able to convert from Markdown to AsciiDoc. The process for this is straightforward: when the AsciiDoc plugin is installed, right-click on a Markdown file, and select ‘Convert to AsciiDoc’. The Markdown syntax will be converted to AsciiDoc, and the file will be renamed from to filename.adoc. This feature has been used on numerous open source projects including Docker and Geb, and has proved to be a stable addition to the plugin. It’s also possible to use the Markdown to AsciiDoc converter in a standalone way or include in your own Java application, as explained here.

Live templates
To save typing, and get familiar with the AsciiDoc syntax, it’s now possible to use Live Templates. All live templates are prefixed with ‘ad-‘, so start typing ‘ad-‘ and you’ll see a list of all the AsciiDoc templates available, like tables, list items, includes, etc. Alternatively, pressing Cmd+J will also bring up the list of templates to choose from.

AsciiDoc live templates

Scratch files
Just want to make a quick note? Scratch files to the rescue, which even include the preview button. Scratch files are documents which are used temporary, and are not saved on the file system. You can create a new Scratch File by accessing Tools -> New Scratch File.

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!