Use Asciidoctor to create great publications

I’m a big fan of Markdown. I really love this idea of lightweight markup – you write plain text, mix it with formatting instructions and get your text formatted. I like it, because it feels very similar to writing the code.

Asciidoctor is another lightweight markup processor. It’s similar to Markdown, but more powerful – it can do more than just making your text bold or underlined. Asciidoctor is what Spring team uses to write their documentation.

Build large documents from smaller parts

It’s usually hard to write a large document with Markdown. Markdown doesn’t have tools to combine a few smaller documents into a single one. Asciidoctor helps you to build larger documents from smaller ones using the include directive:

part1.adoc
1
I am part one.
part2.adoc
1
I am part two.
book.adoc
1
2
3
4
5
6
= My Book

include::part1.adoc[]
include::part2.adoc[]

The end.

Becomes:

Include sources from external files

One of the popular use-cases for Markdown is technical blogging. You write some text that explains what problem you had, you show a piece of code, and then explain how it solves the problem. With Markdown, you have to copy that code into your Markdown markup. With Asciidoctor your can really include the code without copying:

HelloWorldApp.java
1
2
3
4
5
6
7
8
9
package me.loki2302;

public class HelloWorldApp {
  // tag::main[]
  public static void main(String[] args) {
    System.out.println("Hello World!");
  }
  // end::main[]
}
code-inclusion-test.adoc
1
2
3
4
5
6
7
8
9
10
11
12
:source-highlighter: highlightjs

= Hello World in Java

Here's how you write a Hello World in Java:

[source,java,indent=0]
----
include::../../main/java/me/loki2302/HelloWorldApp.java[tag=main]
----

The end.

Becomes:

This feature is super nice, because it ensures that your documentation is always up to date with the source code. Imagine how you include a piece of your test to explain how something works. This code may change later, but the only thing you’ll have to do is to rebuild your documentation.

Illustrate your ideas with diagrams

One of the nice Asciidoctor extensions is asciidoctor-diagram. This extension allows you to use PlantUML right inside your document, so that you don’t have to jump back and forth between text editor and diagram editor:

hamburgers.adoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
= Hard to explain

Some things are really hard to explain.

[plantuml, hamburgers, png]
----
@startuml
repeat
  :Eat a hamburger;
repeat while (Want more?)
@enduml
----

The end.

Becomes:

If it’s the first time you read about PlantUML, definitely do spend 15 minutes to learn more. It’s not just about activity diagrams – they also support class, component and sequence diagrams. There’s also a nice online editor planttext.com with a plenty of sample diagrams.

Conclusion

Asciidoctor integrates nicely with Java projects (see asciidoctor-gradle-plugin) and makes it easy to make documentation one of your build artifacts. The closer you keep your documentation to the code, the easier it is to keep it up to date.

All examples from this post are available in this GitHub repository.