Posts

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

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.

Features

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.

Toolbar
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 filename.md 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.