<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-diagram</artifactId>
<version>1.5.18</version>
</dependency>JBake, Asciidoc and PlantUML
29 February 2020
- Summary
-
When blogging about software topics it becomes quickly compelling to include diagrams into the posts. The project PlantUML for writing UML as diagrams-as-a-code is well suited for those needs. This Blog post is about, how PlantUML is configured with Asciidoc and JBake.
It is really a hype to have everything in version control, namely Git, - and it is always better to version text source than images or binary files. This applies to diagrams, too. With the PlantUML extension Asciidoc offers a way to define diagrams in a declarative way, but include them as images into generated documents, eg. Blog posts like HTML pages.
Configuration
The use of PlantUML is actually not very difficult to configure. Because my
Blog project setup works with JBake’s Maven plugin, we need to add the
dependency of jbake-maven-plugin on the diagram extension:
The diagram extension includes PlantUML.
The next and last step is to set some properties in JBake’s configuration file
jbake.properties:
asciidoctor.option.requires=asciidoctor-diagram
asciidoctor.attributes=sourceDir=src/main/jbake,imagesdir=assets/img/diagrams,imagesoutdir=../../assets/assets/img/diagrams,source-highlighter=highlight.js,icons=fontIf you’re interested in the image directory configuration the Blog post gives more details.
Usage
With described configurations in place, UML diagrams can be easily included in Blog posts. The definition:
[plantuml, "asciidoctor-sequence-diagram", "png"]
----
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
----results in the diagram:
Because PlantUML includes the Creole markup engine, which offers the definition of simple tree like structures, it’s also possible to create diagrams of directory hierarchies for example. The definition:
[plantuml, "file-system-tree", "png", opts="inline"]
----
@startuml
skinparam {
BackgroundColor transparent
BorderColor transparent
}
legend
Root
|_ Element 1
|_ Element 1.1
|_ Element 1.1.1
|_ Element 1.1.2
|_ Element 1.2
|_ Element 1.3
|_ Element 2
|_ Element 2.1
end legend
----renders to:
