asciidoctor-plantuml

PlantUML support for Asciidoctor.JS.


Keywords
asciidoctor, plantuml, antora, asciidoctorjs, diagram, ditaa, asciidoctor-diagram, asciidoctor-extension, javascript
License
ISC
Install
npm install asciidoctor-plantuml@1.5.0

Documentation

Asciidoctor PlantUML Extension

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>