= Asciidoctor PlantUML Extension :plantuml-server-public: http://www.plantuml.com/plantuml :antora-link: https://antora.org[Antora] :toc: macro :icons: font

Extension for https://github.com/asciidoctor/asciidoctor.js[Asciidoctor.js] that provides integration with http://plantuml.com[PlantUML] using https://github.com/plantuml/plantuml-server[PlantUML Server]

ifdef::env-github[]

image:https://img.shields.io/travis/eshepelyuk/asciidoctor-plantuml.js?style=for-the-badge&logo=travis[Travis (.org), link="https://travis-ci.org/eshepelyuk/asciidoctor-plantuml.js"] image:https://img.shields.io/npm/v/asciidoctor-plantuml?style=for-the-badge&logo=npm["npm version", link="https://www.npmjs.com/package/asciidoctor-plantuml"] image:https://img.shields.io/badge/code_style-standardjs-brightgreen?style=for-the-badge[StandardJS, link="https://standardjs.com"]

endif::[]

⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠

This project is out of maintenance. No bug fixes or feature requests are going to be processed.

Do not be frustrated, though !

There's great extension https://github.com/Mogztter/asciidoctor-kroki[asciidoctor-kroki] that supports PlantUML and much more, meanwhile being actively maintained by developers of AsciidoctorJS.

So, the suggestion is - to migrate to asciidoctor-kroki

⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠⚠

toc::[]

== Overview

This extension mimics the behavior of the PlantUML support in https://asciidoctor.org/docs/asciidoctor-diagram[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 https://github.com/plantuml/plantuml-server[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 http://ditaa.sourceforge.net/[Ditaa] and http://www.graphviz.org/doc/info/lang.html[Graphiz (DOT)] syntax as well. Check the http://plantuml.com/[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

https://github.com/plantuml/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 {plantuml-server-public}.
• For performance reason it's recommended to use private one.

One could easily deploy it as Docker container as described in https://github.com/plantuml/plantuml-server#how-to-run-the-server-with-docker[README].

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

=== Configuration

Extension behaviour can be configured via http://asciidoctor.org/docs/user-manual/#attributes[Asciidoctor attributes].

.Supported global or page configuration attributes [cols="3,9"] |=== |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 https://asciidoctor.org/docs/asciidoctor-diagram/#image-output-location[Asciidoctor Diagram] attribute. E.g. ./assets/images

|plantuml-config-file |Analogue of https://github.com/asciidoctor/asciidoctor-diagram#plantuml[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 https://docs.antora.org/antora/2.0/playbook/[site playbook] and providing address of PlantUML server via extension's config.

There's https://github.com/eshepelyuk/asciidoctor-plantuml-antora[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:: + [source,javascript] [subs="verbatim,attributes"] .plantuml.js .... const asciidoctor = require('asciidoctor.js')(); const plantuml = require('asciidoctor-plantuml');

const asciidocContent = ` == PlantUML :plantuml-server-url: {plantuml-server-public} <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:: + [source,html] [subs="verbatim,attributes"] .plantuml.html ....

<script src="node_modules/asciidoctor.js/dist/browser/asciidoctor.js"></script> <script src="node_modules/asciidoctor-plantuml/dist/browser/asciidoctor-plantuml.js"></script> <script> const asciidocContent = ` == PlantUML :plantuml-server-url: {plantuml-server-public} <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>

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

[source,html] [subs="verbatim,attributes"]

----