Hugo, Asciidoctor & PlantUML

PlantUML is a great markup language for creating (not only) UML diagrams. Let’s try and make this tool work with Hugo + Asciidoc.

Asciidoctor has an asciidoctor-diagram package in its toolset. This package should add support not only for PlantUML but also for GraphViz and other graphing markups. Cool. Asciidoctor-diagram was installed when setting up the platform, covered in the previous article

If you try to add a simple PlantUML diagram now, you will probably get an empty picture. The output is generated with an incorrect path.

[plantuml, simple-diagram, svg]
....
class Object1
class Object2

Object1 -> Object 2
....

By default, the resulting image is in the project root directory, whereas the article lies in content/posts/my-article.html and the image is referenced as ./simple-diagram.svg, i.e. it is looked up in content/posts.

We must define an imagesdir attribute in our adoc file that specifies the output directory form PlantUML. See the Asciidoctor-Diagram Documentation.

In this case, the beginning of the document looks as such:

---
title: "Asciidoctor Hugo & PlantUML"
date: "2020-07-31"
draft: false
categories: ["Hugo", "Asciidoc"]
tags: ["asciidoctor", "hugo", "markup", "uml", "configuration"]
---

:imagesoutdir: content/posts/2020-07-31-asciidoctor-hugo-plantuml

= Asciidoctor Hugo & PlantUML

This approach is quite simple to set up and it is working. It has one disadvantage though. PlantUML generates a directory in content/posts/{article_name} and puts the diagram there. It might collide a little with Git since these files are generated upon each build of the site. Don’t forget to update the .gitignore file.