Embed a diagram in a Hugo page

Julian Knight — Fri, 14 Dec 2018 12:56:01 +0000

It is great to be able to define a diagram in code directly in your web pages. This article shows you one way to achieve that using Gravizo.

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 >}}

DOT Language (GraphViz) Example

PlantUML Example

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.

UMLGraph Example

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 )

![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{} )

![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{}
)

Automatically updating Hugo

Julian Knight — Tue, 29 May 2018 21:28:30 +0000

Hugo is still changing very quickly. So it is helpful to be able to easily download and install the latest version directly from GitHub.

Summary

The tricks are firstly to use GitHub’s latest link for software releases and download the webpage. Secondly, to find the link to the actual software download in the content of the page. Once you have this, you can download the latest built version file automatically, unpack it over the top of the existing files and then delete the downloaded file.

NOTE: For hopefully obvious reasons, the Hugo server cannot be running when you run this.

Many thanks to @pgr on the Hugo Discourse for the original idea.

Using PowerShell on Windows 10

# get-hugo.ps1
# Get the latest copy of Hugo for Windows (64bit) from GitHub and install it

# -- CHANGE THESE IF NEEDED -- #

# The folder containing the Hugo `bin` subfolder
$hugoRoot = "c:\Hugo"
# A regular expression to find the right platform link name
$hugoPlatform = "Windows\-64bit\.zip"
# Location of the Hugo executable (relative to $hugoRoot or use absolute path)
$hugoBin = "bin"

# ---------------------------- #

# ================================================== #
# -- Shouldn't need to change anything below here -- #
# ================================================== #

Set-LocationEx -Path $hugoRoot # AKA `cd ...`
# Make TLS 1.2 the primary version otherwise get from most sites will fail
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11, tls"
# Get the GitHub page containing the latest version of Hugo
$latest = Invoke-WebRequest -Uri https://github.com/gohugoio/hugo/releases/latest
# Find the file details for the Windows 64bit version
$file = $latest.ParsedHtml.links | Where-Object{$_.nameProp -match $hugoPlatform} | select pathname, nameProp
# Download the actual file
Invoke-WebRequest -Uri ("https://github.com/" + $file.pathname) -OutFile $file.nameProp
# Unpack the zip file into the `bin` folder - NOTE: This requires PowerShell v5 or above (Windows 10 1709)
Microsoft.PowerShell.Archive\Expand-Archive -Path $file.nameProp -DestinationPath $hugoBin -Force
# Delete the zip file
Remove-Item $file.nameProp

#EOF

Hugo on Much Ado About IT

Embed a diagram in a Hugo page

Summary

MermaidJS

Gravizo

Using a Hugo custom shortcode

Inline Markdown code

Automatically updating Hugo

Summary

Using PowerShell on Windows 10