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

Overview

This extension mimics the behavior of the PlantUML support in Asciidoctor Diagram as close 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
....

block style modifiers are supported
positional attributes are supported
named attributes are supported

Unlike Asciidoctor Diagram, this extension uses PlantUML server for displaying images. Inside image tags produced by it, the src attribute contains a link to 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 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 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.

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)

it’s possible to configure different URL for PlantUML server using Asciidoctor attribute
usage with global extension registry
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>

it’s possible to configure different URL for PlantUML server using Asciidoctor attribute
usage with global extension registry
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>

djencks / asciidoctor-plantuml.js Goto Github PK

asciidoctor-plantuml.js's Introduction

Asciidoctor PlantUML Extension

Overview

PlantUML server

Configuration

Antora integration

Asciidoctor.js integration

Using in Node.JS

Using in browser

Output

asciidoctor-plantuml.js's People

Contributors

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent