Asciidoctor Plantuml Extension

Asciidoctor PlantUml is an extension that enables you to add PlantUML diagrams to your AsciiDoc documents.

This extension differs from others like Asciidoctor Diagram and AsciiDoc PlantUML filter in that this extension does not include PlantUML jar files. Instead it depends on the availability of an external PlantUML server.

Installation

Asciidoctor PlantUml is a RubyGem and can be installed via gem or bundle commands:

$ gem install asciidoctor-plantuml

Creating a diagram

A diagram is written inside an open block inside any asciidoc file:

[plantuml, format="png", id="myId"]

alice → bob : hello bob → alice : hello

Note	You can omit the @startuml/@enduml delimiters. The extension adds them if missing.

Tip	You can create any diagram type supported by PlantUML: sequence, usecase, class, activity, etc.

Warning

You must use an open block, that is delimited by two - instead of four as in a literal block.

The above example is substituted by the following HTML snippet when processed by this extension:

<img id="myId" class="plantuml" src="http://localhost:8080/png/S3dx3fjsaso3d" />

PlantUML Server

By default the image source follows the following URL pattern:

PlantUML URL Pattern

<server base uri>/<format>/<encoded diagram>

The <server base uri> by defaults is http://localhost:8080/plantuml and can be changed using the following code:

require "asciidoctor-plantuml"

Asciidoctor::PlantUml.configure do |conf|
  conf.url = "http://my-private-server:8080"
end

In 2020 the plantuml.com server changed the URL encoding. Now you’ll need to add a small string to signal the encoding. You can enable the new behavior like this:

require "asciidoctor-plantuml"

Asciidoctor::PlantUml.configure do |conf|
  conf.url = "https://www.plantuml.com"
  conf.encoding = 'deflate'
end

The <format> is taken from the block format attribute. It defaults to png and can take any of png, txt and svg.

The <encoded diagram> is generated automatically by this extension. This is the diagram string compressed and encoded in a format that the PlantUML server understands.

Diagram Attributes

There are some attributes you can add to the block to customize how the diagram is displayed:

id: Sets the id attribute of the img element.
alt: Sets the alt attribute of the img element.
width: Sets the width attribute of the img element.
height: Sets the height attribute of the img element.
format: Sets the format of the generated image. Can be either png, svg or txt.

Using Asciidoctor Cli

To load the asciidoctor-plantuml extension when using the asciidoctor command line tool you can use the -r flag:

asciidoctor -r asciidoctor-plantuml sample.adoc

If you want to change the default PlantUML server you can use PLANTUML_URL environment variables:

PLANTUML_URL="https://my-private-server:80/" asciidoctor -r asciidoctor-plantuml sample.adoc

Installing PlantUML Server

Docker

The simplest way to start a PlantUML server is using docker:

docker run -d --name plantuml -p 8081:8080 plantuml/plantuml-server:jetty

Source

In Ubuntu first you need to create a plantuml.war file from the source code:

sudo apt-get install tomcat7 graphviz openjdk-7-jdk git-core maven
git clone https://github.com/plantuml/plantuml-server.git
cd plantuml-server
mvn package

Then copy the plantuml.war file generated when building the package (mvn package) to the Tomcat applications folder:

sudo cp plantuml.war /var/lib/tomcat7/webapps/plantuml.war
sudo chown tomcat7:tomcat7 /usr/share/jetty/webapps/plantuml.war
sudo service restart tomcat7

After restarting Tomcat the application will be running on the server port 8080. You can change the port and other parameters in the /etc/tomcat7/server.xml file.

You may also need to set the JAVA_HOME variable in the /etc/defaults/tomcat7 file if you have the java runtime in a non-standard place.