Guillaume GrossetieNov 4, 2018

Awesome Asciidoctor.js: Use PlantUML extension to render diagrams

Extensions in Asciidoctor.js are very powerful because they open up the language to new use cases. One popular use case is to render PlantUML diagrams. To do that we are going to use the PlantUML extension written by Evgeny Shepelyuk.

In the following example document, we define a simple diagram:

document.adoc

= PlantUML diagram

== First section

[plantuml,format=svg,role=sequence]
....
alice -> bob
....

To render this document, we need to install the dependencies using npm:

$ npm i asciidoctor.js asciidoctor-plantuml

If you prefer Yarn over npm, use this command instead:

$ yarn add asciidoctor.js asciidoctor-plantuml

convert.js

const asciidoctor = require('asciidoctor.js')()
const plantuml = require('asciidoctor-plantuml')

plantuml.register(asciidoctor.Extensions)
asciidoctor.convertFile('document.adoc')

By default the PlantUML extension will use a remote PlantUML server available at www.plantuml.com/plantuml.
Make sure that you have access to this server before generating your documentation.

You can also run the server locally using Docker:

$ docker run -d -p 8080:8080 plantuml/plantuml-server:jetty

Then you will need to override the attribute plantuml-server-url to point to your local server:

const options = {
  attributes: {
    'plantuml-server-url': 'http://localhost:8080'
  }
}
asciidoctor.convertFile('document.adoc', options)

Since version 0.10.0 of the PlantUML extension, you can also generate Ditaa and Graphviz diagrams:

document.adoc

= Ditaa diagram

== First section

[ditaa]
....
+----------+   +-------------+
|cAAA      |   |             |
|          +---+ Application |
| Database |   |      cRED{d}|
|       {s}|   +-------------+
+----------+
....

document.adoc

= Graphviz (DOT) diagram

== First section

[graphviz]
....
digraph foo {
  node [style=rounded]
  node1 [shape=box]
  node2 [fillcolor=yellow, style="rounded,filled", shape=diamond]
  node3 [shape=record, label="{ a | b | c }"]
   node1 -> node2 -> node3
}
....

If you want to learn about the PlantUML extension, you can read the project README on GitHub.

Written with Asciidoctor.js 1.5.9 and Asciidoctor.js PlantUML extension 0.10.0.

Blog