Plain-text diagrams take shape in Asciidoctor!

by Pepijn Van Eeckhoudt -

You write in plain text. You code in plain text. How about creating diagrams in plain text too? Now you can using Asciidoctor Diagram!


Asciidoctor is a fantastic tool to use when writing technical documentation. It allows you to spend more time focusing on your content rather than struggling with WYSIWYG tools.

One task that still pulls your focus away, and is more difficult than it should be, is integrating technical diagrams into your documents. It involves launching a UML or diagramming tool, pushing pixels around the screen to draw the diagrams, exporting the result to a web-friendly image format and linking to them from your source document. The many benefits that AsciiDoc provides in terms of visual consistency, ease of collaboration, etc. are not available when you are working with diagrams.

All that changes today with the announcement of the Asciidoctor Diagram extension. Asciidoctor Diagram integrates existing plain text syntax diagramming tools into the Asciidoctor processing. That means you can embed the source code for your diagrams directly into your documents!

The first version of Asciidoctor Diagram supports the following diagram languages:

These “lightweight diagram languages” are to graphical diagrams what AsciiDoc is to HTML. Another way of saying it:

language analogy diagram

Your first plain-text diagram

The simplest way to add diagrams to your documents is by using diagram blocks. Just add a listing block to your file using the appropriate syntax name (ditaa, graphviz or plantuml) as the block name (aka style).

                   | Asciidoctor |-------+
                   |  Diagram    |       |
                   +-------------+       | PNG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /----------------\
 |        | --+ Asciidoctor +--> |                |
 |  Text  |   +-------------+    |Beautiful output|
 |Document|   |   !magic!   |    |                |
 |     {d}|   |             |    |                |
 +---+----+   +-------------+    \----------------/
     :                                   ^
     |          Lots of work             |

When the Asciidoctor Diagram extension processes this type of block, it will read the body of the block, pass it to the ditaa library, write the resulting image to disk and generate an image block. Here’s how it appears in the rendered document:

sample ditaa diagram


Generating one of these images is fairly quick, but if you start adding lots of diagrams to your document the processing time can start adding up. Asciidoctor Diagram optimizes the processing by keeping track of diagram metadata in *.cache files and will only regenerate the images if the diagram source code was modified. This keeps incremental rendering of documents a speedy process.

Controlling the output

By default Asciidoctor Diagram creates PNG images and calculates an output file name automatically based on the diagram source code. This behavior can be overridden using the target and format attributes. You can specify these attributes as the first and second positional attributes or as explicitly named attributes. An SVG file with a specific name a Graphviz diagram can be generated as follows

[graphviz, dot-example, svg]
digraph g {
    a -> b
    b -> c
    c -> d
    d -> a

After the magic happens, you’ll see:

sample graphviz diagram
Asciidoctor Diagram bundles both the ditaa and PlantUML libraries and will use them to generate diagrams. In order to generate diagrams using Graphviz, you must install it separately (meaning the dot command must be available on your PATH).

Asciidoctor Diagram turns the diagram blocks into image blocks and applies any additional attributes. This means you can use the normal Asciidoctor facilities to control the positioning of the generated image. Block titles and IDs can also be assigned in the same way.

.The PlantUML block extension class
[plantuml, sample-plantuml-diagram, alt="Class diagram", width=135, height=118]
class BlockProcessor
class PlantUmlBlock
BlockProcessor <|-- PlantUmlBlock

Here’s what gets rendered:

Class diagram
The PlantUML block extension class

Including external diagrams

It might not always be desirable to embed the source code for diagrams in your document. External diagrams can also be processed using the block macro syntax. This is very similar to how you typically include images in your documents.

plantuml::classes.txt[format=svg, alt="Class diagram", width=300, height=200]

Enabling the extension

Asciidoctor 0.1.4 does not yet allow extensions to be enabled via the command line. That is a feature coming in Asciidoctor 1.5.0. Until then, the easiest way to enable the extensions is to use a short wrapper script. The following script, asciidoctor-diagram, loads and registers the Asciidoctor Diagram extension, then invokes Asciidoctor in the same way as the asciidoctor command.

asciidoctor-diagram launch script
#!/usr/bin/env ruby

require 'asciidoctor' (1)
require 'asciidoctor/cli/options'
require 'asciidoctor/cli/invoker'

require 'asciidoctor-diagram' (2)

invoker = ARGV (3)
exit invoker.code
1 Loads Asciidoctor
2 Loads and registers the Asciidoctor Diagram extensions
3 Invoke the Asciidoctor CLI

Put the asciidoctor-diagram script on your PATH, make it executable and use it in place of the asciidoctor command.

$ asciidoctor-diagram my-doc-with-cool-diagrams.adoc

After running the asciidoctor-diagram script on your document, go check out the cool diagrams it made for you!

Go play!

Now it’s time to go play with Asciidoctor Diagram. Explore what you can do with it and how it can be improved. To help you get started, check out these examples in the Asciidoctor Diagram repository. We look forward to hearing from you on the Asciidoctor discussion list or the Asciidoctor Diagram issue tracker.

Together, we can make diagrams and documentation come to life out of plain ol' text!

Introducing Asciidoctor.js live preview in your browser

by Guillaume Grossetie -

I’d like to introduce you to the easiest way to render any AsciiDoc file, local or remote, as HTML directly in your browser!

All you need to do is install the Chrome extension or the Firefox add-on. Then you can preview any AsciiDoc file as HTML just by visiting it!

How it works

The Chrome extension and the Firefox add-on use Asciidoctor.js to render AsciiDoc as HTML inside your browser. Both provide a toggle button to switch between HTML output and AsciiDoc source.

Here you can see a local AsciiDoc file rendered inside of Chrome.

chrome extension enabled
Chrome extension in action
You can view any AsciiDoc file on GitHub through the lens of Asciidoctor.js with this extension! Simply navigate to the file in the GitHub web interface (try this blog post) and click the Raw button that appears above the file preview. Looks much better, doesn’t it?


Currently, we are using Asciidoctor.js based on Asciidoctor 0.1.2. We planned to cross-compile the newly-released Asciidoctor 0.1.4 to Javascript, to support the latest and greatest features!

We are also working on adding some cool new features :

  • browser-based editor using MarkItUp!

  • live reload to automatically refresh on local file changes

  • and many more…​


We’re always open for patches, better documentation, feature requests, evangelizing or any help you’re able to provide.

  • 1 of 1