Asciidoctor Plantuml Extension
Asciidoctor PlantUml is an extension that enables you to add PlantUML diagrams to your AsciiDoc documents.
Asciidoctor PlantUml is a RubyGem and can be installed via
$ 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
|You can omit the @startuml/@enduml delimiters. The extension adds them if missing.|
|You can create any diagram type supported by PlantUML: sequence, usecase, class, activity, etc.|
|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" />
By default the image source follows the following 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.
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
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
The simplest way to start a PlantUML server is using docker:
docker run -d --name plantuml -p 8081:8080 plantuml/plantuml-server:jetty
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.