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.
Asciidoctor PlantUml is a RubyGem and can be installed via gem or bundle
commands:
$ gem install asciidoctor-plantuml
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" />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"
endIn 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'
endThe <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.
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
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 packageThen 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 tomcat7After 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.