Asciidoctor PlantUML Extension

Extension for Asciidoctor.js that provides integration with PlantUML using PlantUML Server

Table of Contents

• Overview
  • PlantUML server
  • Configuration
• Antora integration
• Asciidoctor.js integration
  • Using in Node.JS
  • Using in browser
  • Output

Overview

This extension mimics the behavior of the PlantUML support in Asciidoctor Diagram as closely as possible. Positional and named attributes as well as PNG and SVG formats are supported.

PlantUML example

[plantuml#myId,mydiagram,svg,role=sequence] (1) (2) (3)
....
alice -> bob
....

1. block style modifiers are supported

2. positional attributes are supported

3. named attributes are supported

Unlike Asciidoctor Diagram, this extension uses PlantUML server for displaying images. The default behavior is that generated image tags will have the src attribute contain a link to a PlantUML server.

Note	Since the PlantUML server supports some other formats, it’s possible to use the Ditaa and Graphiz (DOT) syntax as well. Check the PlantUML website for the complete list of supported diagrams.

Ditaa example

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

Note	Only PNG generation is supported for Ditaa diagrams.

Graphviz (DOT) example

[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
}
....

PlantUML server

PlantUML server is a standalone web application exposing an HTTP API that allows generating diagram images on the fly.

It can be used in two modes:

• Public instance, for example this one http://www.plantuml.com/plantuml.

• For performance reason it’s recommended to use private one.

  One could easily deploy it as Docker container as described in README.

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

Configuration

Extension behaviour can be configured via Asciidoctor attributes.

Table 1. Supported global or page configuration attributes

Attribute	Description
plantuml-server-url	mandatory PlantUML Server instance URL. Will be used for generating diagram src. E.g. http://www.plantuml.com/plantuml
plantuml-fetch-diagram	If set, images will be downloaded and saved to local folder. img tags will be pointing to local folder. Otherwise, img tags will have src attribute pointing to :plantuml-server-url:
imagesoutdir	Analogue of Asciidoctor Diagram attribute. E.g. ./assets/images
plantuml-config-file	Analogue of PlantUML config attribute.
plantuml-default-format	Sets the default output format, which is normally png. This can be overriden in a specific diagram with the format attribute.
plantuml-default-options	Sets the default for the options attribute. May be set to inline for inline svg, or interactive for interactive object.

Antora integration

Integration is just the matter of enabling the extension in site playbook and providing address of PlantUML server via extension’s config.

There’s sample repository demonstrating usage of this extension in Antora.

Asciidoctor.js integration

Using in Node.JS

Install dependencies

$ yarn add asciidoctor.js asciidoctor-plantuml

Create file with following content and run it

plantuml.js

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

const asciidocContent = `
== PlantUML
:plantuml-server-url: http://www.plantuml.com/plantuml (1)
[plantuml]
----
alice -> bob
bob ..> alice
----
`;

plantuml.register(asciidoctor.Extensions);
console.log(asciidoctor.convert(asciidocContent)); (2)

const registry = asciidoctor.Extensions.create();
plantuml.register(registry);
console.log(asciidoctor.convert(asciidocContent, {'extension_registry': registry})); (3)

1. it’s possible to configure different URL for PlantUML server using Asciidoctor attribute

2. usage with global extension registry

3. usage with custom registry

Using in browser

Install dependencies

$ yarn add asciidoctor.js asciidoctor-plantuml

Create file with following content and open in in browsert

plantuml.html

<html>
<head>
<script src="node_modules/asciidoctor.js/dist/browser/asciidoctor.js"></script>
<script src="node_modules/asciidoctor-plantuml/dist/browser/asciidoctor-plantuml.js"></script>
</head>
<body>
    <script>
const asciidocContent = `
== PlantUML
:plantuml-server-url: http://www.plantuml.com/plantuml (1)
[plantuml]
----
alice -> bob
bob ..> alice
----
`;

var asciidoctor = Asciidoctor();
var plantuml = AsciidoctorPlantuml;

plantuml.register(asciidoctor.Extensions);
console.log(asciidoctor.convert(asciidocContent)); (2)

const registry = asciidoctor.Extensions.create();
plantuml.register(registry);
console.log(asciidoctor.convert(asciidocContent, {'extension_registry': registry})); (3)
    </script>

</body>
</html>

1. it’s possible to configure different URL for PlantUML server using Asciidoctor attribute

2. usage with global extension registry

3. usage with custom registry

Output

Regardless of global or custom registry usage, produced HTML output will look like

<div class="sect1">
<h2 id="_plantuml">PlantUML</h2>
<div class="sectionbody">
<div class="imageblock plantuml">
<div class="content">
<img src="http://www.plantuml.com/plantuml/png/Iyp9J4vLqBLJICfFuW9Y1JqzEuL4a200" alt="diagram">
</div>
</div>
</div>
</div>