AsciiDoctor-Diagram is an extension of Asciidoctor that enables you to create diagrams using plaintext directly in your AsciiDoc files. Asciidoctor-Diagram supports a number of formats, including:

For example, PlantUML markup can be used to create a sequence diagram:

.PlantUML diagram -- ISO{nbsp}8583 dual-message flow
[plantuml,target="sample-plantuml-diagram",format=svg]
....
@startuml
!theme lightgray (1)
Merchant -> Acquirer: 0100 Auth request
Acquirer -> Issuer: 0100 Auth request
Acquirer <-- Issuer: 0110 Auth response
Merchant <-- Acquirer: 0110 Auth response
... On completion: ...
Merchant -> Acquirer: 0220 Tran advice
Acquirer -> Issuer: 0220 Tran advice
Acquirer <-- Issuer: 0230 Tran advice response
Merchant <-- Acquirer: 0230 Tran advice response
@enduml
....

  1. PlantUML now includes a number of official themes that can be referenced using the !theme directive.

This results in:

sample plantuml diagram
Figure 1. PlantUML diagram — ISO 8583 dual-message flow

To add Asciidoctor-Diagram functionality to Hugo, I did the following (using the instructions provided by Andreas Longo in Generate diagrams with Asciidoctor and Hugo):

  1. Added an entry for Asciidoctor-Diagram to the Gemfile file in the project’s root folder:

    1
2
3
4

    source 'https://rubygems.org'
gem 'asciidoctor'
gem 'asciidoctor-diagram'
gem 'rouge'

  2. Ran the command bundle to install the Asciidoctor-Diagram gem locally and update the Gemfile.lock file.

  3. In the <root-folder>/config/_default/config.toml file, I added the following highlighted lines:

    1
2
3
4
5
6
7
8
9

    [markup.asciidocExt]
    extensions = ["asciidoctor-diagram"]
    workingFolderCurrent = true # (1)
    [markup.asciidocExt.attributes]
        diagram-cachedir = ".cache"
        experimental = true
        source-highlighter = "rouge"
        relfileprefix = "../"
        relfilesuffix = "/"

    1. The Hugo documentation states that this is required when using Asciidoctor-Diagram.

  4. Added --destination public to the build command: hugo --minify --gc --destination public. According to the Hugo documentation, this is required if using an external Asciidoctor command. In my case, I updated the command in the package.json file, but it could also be in the netlify.toml, both of which are in the root folder.

  5. Added the <root-folder>/content/english/blog/.asciidoctor folder to .gitignore. This folder fills up with lots of temporary files, as well as the output diagram files.

Although it’s convenient to be able to create diagrams using plaintext, I’m not entirely sure that adding this functionality to a Hugo site run on Netlify is a good idea. Doing so means that each time the site is built, the diagrams are re-generated, adding time and build minutes to the process.