Embed a diagram in a Hugo page

Summary 🔗︎

We want to be able to generate neat diagrams for our website. This can, of course, be done offline using Microsoft Visio or some other diagramming tool. There are online ones too. But sometimes, we want to be able to generate a diagram using code or we just need something quick and simple. That is where tools such as GraphViz or PlantUML come in handy.

But currently, there are no direct addin’s for Hugo to achieve this.

We can, however, use an external tool to create the diagram dynamically from code embedded in the page. There are several tools that we could use, I will update this page as and when I try those tools.

MermaidJS 🔗︎

MermaidJS is a JavaScript library that you can easily embed on your page. It is widely used and well supported.

Mermaid supports several types of diagram including: Sequence, Flowchart, Gantt (timeline), Class (beta), Git graph (beta).

MermaidJS is available for installation on your own configuration using Node.JS or you can use the UnPkg CDN.

Gravizo 🔗︎

We can use Gravizo to embed diagrams of various kinds in a web site.

Gravizo has a number of ways to embed or access the source and supports GraphViz (DOT language), PlantUML and UMLGraph (though there are some limitations on the latter).

Graviso will produce the following types of diagram: Graph (DOT), UML Sequence, UML State, UML Class, Activity, SVG custom.

You can output the diagram as SVG or PNG graphics by changing the URL.

Note that you are using a 3rd party website if you use these methods. As always, I recommend turning off 3rd-party cookie support in your browser to help prevent any tracking. The advantage however, is that you don’t need any JavaScript on your page.

Using a Hugo custom shortcode 🔗︎

shortcodes/gravizo.html

{{ $title := "Diagram" }}
{{ if .IsNamedParams }}
  {{ with .Get "title" }}
    {{ $title = . }}
  {{ end }}
{{ else }}
  {{ with .Get 0 }}
    {{ $title = . }}
  {{ end }}
{{ end }}

<figure>
  <img
    src='https://g.gravizo.com/svg?{{ .Inner }}'
    alt='{{ $title  }}'
    />
    <figcaption>{{ $title  }}</figcaption>
</figure>

To use:

{ {< gravizo "DOT Language (GraphViz) Example" >}}
  digraph G {
    aize ="4,4";
    main [shape=box];
    main -> parse [weight=8];
    parse -> execute;
    main -> init [style=dotted];
    main -> cleanup;
    execute -> { make_string; printf}
    init -> make_string;
    edge [color=red];
    main -> printf [style=bold,label="100 times"];
    make_string [label="make a string"];
    node [shape=box,style=filled,color=".7 .3 1.0"];
    execute -> compare;
  }
{ {< /gravizo >}}

Note that the UMLGraph example below from the Gravizo website doesn’t work in this context - it is unclear why but I expect it to be something to do with an invalid HTML entity.

Inline Markdown code 🔗︎

An alternative to needing a shortcode is to embed the source directly into the page.

Note that this method does not allow blank lines so the source is hard to read. This is because Markdown uses a blank line as a paragraph separator.


![Alt text](https://g.gravizo.com/svg?
@startuml;
actor User;
participant "First Class" as A;
participant "Second Class" as B;
participant "Last Class" as C;
User -> A: DoWork;
activate A;
A -> B: Create Request;
activate B;
B -> C: DoWork;
activate C;
C --> B: WorkDone;
destroy C;
B --> A: Request Created;
deactivate B;
A --> User: Done;
deactivate A;
@enduml
)

This method does allow the UMLGraph example to work as long as you remove the blank lines:


![Alt text](https://g.gravizo.com/svg?
  /**
    *Structural Things
    *@opt commentname
    *@note Notes can
    *be extended to
    *span multiple lines
    */
    class Structural{}
    /**
    *@opt all
    *@note Class
    */
    class Counter extends Structural {
            static public int counter;
            public int getCounter%28%29;
    }
    /**
    *@opt shape activeclass
    *@opt all
    *@note Active Class
    */
    class RunningCounter extends Counter{}
)