Creating Flowcharts in Hugo (Part 1)

Mermaid is an external library that allows us to generate diagrams and flowcharts in Hugo markdown content. Though Hugo currently does not provide default templates for Mermaid diagrams, we can easily create a shortcode for this purpose. This series of articles offer a sample of basic flowcharts that can be used in Hugo content.

Table of Contents

Introduction

Deployment in Hugo

In your layouts/partials folder, add the following lines to the existing header.html file:

1<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
2<script>
3  mermaid.initialize({ startOnLoad: true, securityLevel: "loose" });
4</script>

If the header.html file does not exist, copy and paste from the existing one in theme/layouts/partials folder.

Tip: Do not modify the header file in your theme folder as this may be overwritten if your theme is updated.

Then, create a shortcode in your layouts/shortcodes folder. Let’s call it mermaid.html and add the following lines.

 1{{ $_hugo_config := `{ "version": 1 }` }}
 2<div class="mermaid" align="
 3{{ if .Get "align" }}
 4{{ .Get "align" }}
 5{{ else }}
 6center
 7{{ end }}"
 8>
 9{{ safeHTML .Inner }}
10</div>

Finally, to deploy the mermaid diagram, insert the following shortcode in any part of your content:

1{{<  mermaid >}}
2  Mermaid code.
3{{< /mermaid >}}

Flowchart Basic Syntax

All flowcharts in Mermaid are composed of nodes (the geometric shapes) and the arrows (directed line segments). The mermaid code defines the way that these nodes and arrows interact to create complicated flowcharts.

Node

1flowchart
2  id

flowchart id

A node with text

1flowchart
2    id1[Some text]

flowchart id1[Some text]

Graph

1flowchart TD
2    Start --> Stop

flowchart TD Start --> Stop

The TD option after flowchart indicates the chart flows in a top-down manner. Possible FlowChart orientations are:

Orientation	Meaning
TD	Top-down
TB	Top to Bottom
BT	Bottom to Top
LR	Left to Right
RL	Right to Left

The following flowchart is oriented from left to right (LR).

1flowchart LR
2    Start --> Stop

flowchart LR Start --> Stop

Node shapes

The following sections emumerate the possible node shapes available in Mermaid.

Round Edges

1flowchart LR
2    id1(Some text)

flowchart LR id1(Some text)

Square Edges

1flowchart LR
2    id1[Some text]

flowchart LR id1[Some text]

Stadium-shaped Node

1flowchart LR
2    id1([Some text])

flowchart LR id1([Some text])

Subroutine-shaped Node

1flowchart LR
2    id1[[Some text]]

flowchart LR id1[[Some text]]

Cylinder-shaped Node

1flowchart LR
2    id1[(Some text)]

flowchart LR id1[(Some text)]

Circle Node

1flowchart LR
2    id1((Some text))

flowchart LR id1((Some text))

Flag-Shaped Node

1flowchart LR
2    id1>Some text]

flowchart LR id1>Some text]

Rhombus Node

1flowchart LR
2    id1{Some text}

flowchart LR id1{Some text}

Hexagon Node

1flowchart LR
2    id1{{Some text}}

flowchart LR id1{{Some text}}

Trapezoidal Nodes

Parallelogram Node A

1flowchart LR
2    id1[/Some text/]

flowchart LR id1[/Some text/]

Parallelogram Node B

1flowchart LR
2    id11[\Some text\]

flowchart LR id1[\Some text\]

Trapezoid Node A

1flowchart LR
2    id1[/Some text\]

flowchart LR id1[/Some text\]

Trapezoid Node B

1flowchart LR
2    id1[\Some text/]

flowchart LR id1[\Some text/]

Double-circle Node

1flowchart LR
2    id1(((Some text)))

flowchart LR id1(((Some text)))

Links between Nodes

Nodes can be connected with links/edges. It is possible to have different types of links or text attachments to a link.

Link with Arrow Head

1flowchart LR
2    A-->B

flowchart LR A-->B

Open Link

1flowchart LR
2    A---B

flowchart LR A---B

Text on Link

1flowchart LR
2  A-- text on link ---B

flowchart LR A-- text on link ---B

Tip: If you want a longer link, add more dashes to the right side of the text.

1flowchart LR
2  A-- text on link ----B

flowchart LR A-- text on link ----B

Text on Link with Arrow

1flowchart LR
2    A-- text on link -->B

flowchart LR A-- text on link -->B

Dotted Link with Arrow

1flowchart LR
2    A-.->B

flowchart LR A-.->B

Text on Dotted Link with Arrow

1flowchart LR
2    A-. text .-> B

flowchart LR A-. text .-> B

Text on Thick Link

1flowchart LR
2    A == text ==> B

flowchart LR A == text ==> B

Chaining Links

1flowchart LR
2    A --> B --> C

flowchart LR A --> B --> C

We can increase the length of the arrow from A to B by adding more dashes.

1flowchart LR
2    A ---> B --> C

flowchart LR A ---> B --> C

1flowchart LR
2    A ----> B --> C

flowchart LR A ----> B --> C

We can add text on the arrows as expected.

1flowchart LR
2    A -- text1 --> B -- text2 --> C

flowchart LR A -- text1 --> B -- text2 --> C

However, adding more dashes will result in the text becoming a node.

1flowchart LR
2    A --- text1 ---> B -- text2 --> C

flowchart LR A --- text1 ---> B -- text2 --> C

Adding more dashes on the side where you desire longer length.

1flowchart LR
2    A ---- text1 --> B -- text2 --> C

flowchart LR A ---- text1 --> B -- text2 --> C

❓ Question What if we want a longer arrow with text?

Answer

We can use the following syntax where the text is enclosed within vertical bars | | and place more dashes in the arrow.

1flowchart LR
2  A ---->|text1|B -- text2 --> C

flowchart LR A ---->|text1|B -- text2 --> C

Alternatively, we can add the extra dashes on the right side of the text. The text will remain centered.

1flowchart LR
2  A -- text1 ----> B -- text2 --> C

flowchart LR A -- text1 ----> B -- text2 --> C

The syntax used to generate different lengths of the links (with or without arrows) are summrized in the following table.

Length	1	2	3
Link	- - -	- - - -	- - - - -
Link with Arrow	- ->	- - ->	- - - ->
Thick Link	===	====	=====
Thick Link with Arrow	==>	===>	====>
Dotted Link	-.-	-..-	-…-
Dotted Link with Arrow	-.->	-..->	-…->

Dependencies of Nodes

1flowchart TD
2    A --> C
3    A --> D
4    B --> C
5    B --> D

flowchart TD A --> C A --> D B --> C B --> D

We could have used the following more compact syntax to produce the above flowchart.

1flowchart TD
2  A & B--> C & D

flowchart TD A & B--> C & D

❓ Question What if we want to remove the arrow from `B` to `C`?

Answer

1flowchart TD
2  A --> C & D
3  B --> D

flowchart TD A --> C & D B --> D

A neat example.

1flowchart TD
2  a --> b & c--> d

flowchart TD a --> b & c--> d

New Arrow Types

1flowchart LR
2    A --o B
3    B --x C

flowchart LR A --o B B --x C

Multi-directional Arrows

1flowchart LR
2    A o--o B
3    B <--> C
4    C x--x D

flowchart LR A o--o B B <--> C C x--x D

More examples

In the following example, an extra dash is added in the link from node B to node E to indicate it is a longer arrow than the rest.

1flowchart TD
2    A[Start] --> B{Pass?}
3    B --Yes--> C[OK]
4    C --> D[Rethink]
5    D --> B
6    B --->|No|E[End]

flowchart TD A[Start] --> B{Pass?} B --Yes--> C[OK] C --> D[Rethink] D --> B B --->|No|E[End]

Alternatively, we can use the syntax B --No---> E[End] with more dashes added to the right side of the text to indicate a longer length of the arrow from B to E.

1flowchart TD
2    A[Start] --> B{Pass?}
3    B --Yes--> C[OK]
4    C --> D[Rethink]
5    D --> B
6    B --No---> E[End]

flowchart TD A[Start] --> B{Pass?} B --Yes--> C[OK] C --> D[Rethink] D --> B B --No---> E[End]

Special Characters within Text

It is possible to put text within quotes " " in order to render special characters.

1flowchart LR
2  id1["This is the (text) in the box"]

flowchart LR id1["This is the (text) in the box"]

Adding Emojis to Text:

1flowchart LR
2  id1[" ☢ Do not enter!"]

flowchart LR id1["☢" Do not enter!]

A complete list of emojis can be found here .