With the Asciidoctor diagram extension we can include diagrams that are written in plain text. For example PlantUML or Ditaa diagrams. The extension offers a block processor where we include the diagram definitions in our Asciidoctor document. But there is also a block macro processor. With the block macro processor we can refer to an external file. The file is processed and the resulting image is in our output document.
In our Groovy scripts we can use the
@Grab annotation. With this annotation we define dependencies for our script and they will be automatically downloaded and added to the class path when we run our script. When we use IntelliJ IDEA we can use a nice intention that is part of the IntelliJ IDEA Groovy support to download the dependencies from our IDE editor. IDEA downloads the dependencies and add it to the project module dependencies. This is useful, because this will also adds code completion for the classes in the dependency to our editor.
PlantUML supports sprites to be used in diagrams. A sprite is text encoded monochrome graphic we can reference using the syntax
<$spriteName>. The sprite is defined using hexadecimal values. We can define a set of hexadecimal values to create our sprite, but we can also generate the correct values from for example a PNG image.
In a previous post we learned how to use a
together block to keep elements together. We can also layout elements in a different way: using hidden lines. We define our elements and by using the keyword
[hidden] in our line definition the elements are layout as if there was a line, but we don’t see it. This gives us great flexibility on how we layout our elements.
We have a lot of ways to customize our PlantUML diagrams. We can change the colors and we can even set gradients as color. A gradient has two colors and a direction. The direction of the gradient is set by the separator between the two colors. We can use the following separators to set the gradient direction:
/: direction top left to bottom right
\: direction bottom left to top right
|: direction left to right
-: direction top to bottom
PlantUML has some features that come from the underlying software to create diagrams. Graphviz is used by PlantUML and we can use Graphviz features in our PlantUML diagrams. For example we can align multi-line text of labels to be either center (default), left or right aligned using a Graphviz feature. When we want to text to be center aligned we simply use the new-line character
\n. If we want to have our text left aligned we use
\l instead of
\n. And to right align the text we use
Normally if we type an URL in Asciidoctor that starts with a scheme Asciidoctor knows about, the URL is turned into a hyperlink. The following schemes are recognized by Asciidoctor:
If we want to keep our URL as text and not a link we must prepend our URL with a backslash (
\). This way Asciidoctor will not transform the URL to a hyperlink in our output.
In the following example we have URL that is transformed to a link, followed by the same URL but with a backslash (
\) before it, that is not transformed:
== URL not as a link
The URL http://ift.tt/2i6Rp1o should
be turned into a hyperlink.
But now the URL \http://ift.tt/2i6Rp1o should
just be text and not a hyperlink.
If we transform our document to HTML with Asciidoctor we get the following result:
Written with Asciidoctor 18.104.22.168.
With Asciidoctor markup we can position images in our document. We can even float images, so text can next to an image, inside only below or about the image. We can also define multiple images to float, so the images are displayed on the same line next to each other. Any text that follows these images is also displayed next to the images. If we want only to have floating images, but the text starting under the images we can place the images inside an open block and assign the block the role
In a previous post we learned how to use data in CSV and DSV format. Recently we can also include tab separated values (TSV) in a Asciidoctor table. We must set the table attribute
format to the value
tsv. The data can be inside the document, but also defined in an external file which we add with the