codericbrainstorm / asciidoctor-plantuml.js

Port of Ruby based Asciidoctor Plantuml Extension to JavaScript and Asciidoctor.js.

Asciidoctor Plantuml Extension

Table of Contents

• Project status
• Overview
  • Extension installation
  • PlantUML server
  • Configuration
• Antora integration
• Asciidoctor.js integration

Port of Ruby based Asciidoctor Plantuml Extension to JavaScript and Asciidoctor.js.

Project status

Overview

The extension tries to mimic behaviour of [plantuml] block from Asciidoctor Diagram.

Unlike original code, it uses PlantUML server for displaying images. Inside image tags produced by the extension the src attribute contains a link to PlantUML server.

During page rendering diagram is generated on PlantUML Server and displayed in browser.

Extension installation

$ npm i asciidoctor-plantuml

PlantUML server

PlantUML server is a standalone web application exposing 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 can be configured via Asciidoctor attributes.

Table 1. Supported 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

Antora integration

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

I’ve created sample Antora component demonstrating usage of this extension. Below are the steps to build and run sample site with PlantUML support.

1. Clone project from GitHub

   $ git clone https://github.com/eshepelyuk/asciidoctor-plantuml-antora.git
   $ cd asciidoctor-plantuml-antora

2. Install required modules

   $ npm i -g @antora/cli
   $ npm i -g @antora/site-generator-default
   $ npm i asciidoctor-plantuml
   $ npm i -g serve

3. Generate site

   $ antora generate site.yml

4. Start web server

   $ serve build

5. Check results

Open http://localhost:5000 in browser.

Asciidoctor.js integration

Sample code

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

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

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

const registry = asciidoctor.Extensions.create();
plantuml.register(registry);
console.log(asciidoctor.convert(ADOC, {'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

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"><div class="content"><img class="plantuml" src="http://www.plantuml.com/plantuml/png/Iyp9J4vLqBLJICfFuW9Y1JqzEuL4a200"/></div></div>
</div>
</div>