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:

= PlantUML diagram

== First section

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
const asciidoctor = require('asciidoctor.js')()
const plantuml = require('asciidoctor-plantuml')


By default the PlantUML extension will use a remote PlantUML server available at
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:

= Ditaa diagram

== First section

+----------+   +-------------+
|cAAA      |   |             |
|          +---+ Application |
| Database |   |      cRED{d}|
|       {s}|   +-------------+
= Graphviz (DOT) diagram

== First section

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.