Extended Shortcode - mermaid - FixIt

Lruihao included in Documentation

2023-02-24 2023-03-22 1052 words 5 minutes 1 views

/documentation/content-management/shortcodes/extended/mermaid/featured-image.png

Contents

Note

This article was last updated on 2023-03-22, the content may be out of date.

FixIt 0.2.15 | CHANGED

The mermaid shortcode supports diagrams in Hugo with Mermaid library.

Mermaid is a library helping you to generate diagram and flowcharts from text, in a similar manner as Markdown.

Just insert your mermaid code in the mermaid shortcode and that’s it.

Flowchart

Example flowchart mermaid input:

1
2
3
4
5
6
7
{{< mermaid >}}
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
{{< /mermaid >}}

The rendered output looks like this:

Sequence Diagram

Example sequence diagram mermaid input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{{< mermaid >}}
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!
{{< /mermaid >}}

The rendered output looks like this:

Class Diagram

Example class diagram mermaid input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{{< mermaid >}}
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }
{{< /mermaid >}}

The rendered output looks like this:

State Diagram

Example state diagram mermaid input:

1
2
3
4
5
6
7
8
9
{{< mermaid >}}
stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
{{< /mermaid >}}

The rendered output looks like this:

Entity Relationship Diagram

Example entity-relationship diagram mermaid input:

1
2
3
4
5
6
{{< mermaid >}}
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
{{< /mermaid >}}

The rendered output looks like this:

User Journey

Example user journey mermaid input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{{< mermaid >}}
journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me
{{< /mermaid >}}

The rendered output looks like this:

Gantt

Example Gantt mermaid input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{{< mermaid >}}
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2              :         des4, after des3, 5d
{{< /mermaid >}}

The rendered output looks like this:

Pie Chart

Example pie chart mermaid input:

1
2
3
4
5
6
{{< mermaid >}}
pie
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
{{< /mermaid >}}

The rendered output looks like this:

Requirement Diagram

Example requirement diagram mermaid input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{{< mermaid >}}
requirementDiagram

requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}

element test_entity {
type: simulation
}

test_entity - satisfies -> test_req
{{< /mermaid >}}

The rendered output looks like this:

Git Graph

Example git graph mermaid input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{{< mermaid >}}
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit
{{< /mermaid >}}

The rendered output looks like this:

C4 Diagrams ⚠️

C4 Diagram: This is an experimental diagram for now. The syntax and properties can change in future releases. Proper documentation will be provided when the syntax is stable.

Mermaid’s c4 diagram syntax is compatible with plantUML. See example below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{{< mermaid >}}
    C4Context
      title System Context diagram for Internet Banking System
      Enterprise_Boundary(b0, "BankBoundary0") {
        Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
        Person(customerB, "Banking Customer B")
        Person_Ext(customerC, "Banking Customer C", "desc")

        Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

        System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

        Enterprise_Boundary(b1, "BankBoundary") {

          SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

          System_Boundary(b2, "BankBoundary2") {
            System(SystemA, "Banking System A")
            System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
          }

          System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
          SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

          Boundary(b3, "BankBoundary3", "boundary") {
            SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
            SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
          }
        }
      }

      BiRel(customerA, SystemAA, "Uses")
      BiRel(SystemAA, SystemE, "Uses")
      Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
      Rel(SystemC, customerA, "Sends e-mails to")

      UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
      UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
      UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
      UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
      UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")

      UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
{{< /mermaid >}}

Mindmap ⚠️

Bump Mermaid from 9.x to 10.x

Timeline Diagram ⚠️

Bump Mermaid from 9.x to 10.x

Mermaid Themes

Available themes are as follows:

default - This is the default theme for all diagrams.
neutral - This theme is great for black and white documents that will be printed.
dark - This theme goes well with dark-colored elements or dark-mode.
forest - This theme contains shades of green.
base - This is the only theme that can be modified. Use this theme as the base for customizations.

Head to the Theme Configuration | Mermaid page to learn more about dynamic and integrated theme configuration.

Site-wide Themes

You can configure mermaid themes globally in config.toml via the params.mermaid parameter.

Diagram-specific Themes

To customize the theme of an individual diagram, use the init directive.

Example of init directive setting the theme to forest:

1
2
3
4
5
{{< mermaid >}}
%%{init: {'theme':'forest'}}%%
  graph TD
    a --> b
{{< /mermaid >}}