Mermaid Diagrams

Tue, 23 Dec 2025 00:00:00 +0000

This theme supports Mermaid diagrams directly in your Markdown content. Mermaid lets you create diagrams and visualizations using text and code.

About Mermaid.js

This theme integrates Mermaid.js (v11) to render diagrams from text definitions within Markdown code blocks. Mermaid is a JavaScript-based diagramming and charting tool that uses text-based syntax inspired by Markdown.

For complete syntax documentation, see the Mermaid.js documentation.

Getting Started

To create a Mermaid diagram, simply use a fenced code block with mermaid as the language identifier:

1
2
3
4
5


```mermaid
graph TD
 A[Start] --> B[Process]
 B --> C[End]
```

The diagram will be automatically rendered when the page loads.

Features

Auto-detection: Mermaid script only loads on pages that contain diagrams
Theme Support: Diagrams automatically adapt to light/dark mode
HTML Labels: Support for HTML content in labels (like <br/> for line breaks)
Configurable: Customize version, security level, and more in your site config

Configuration

You can configure Mermaid in your site config:

hugo.yaml:

1
2
3
4
5
6
7
8
9


params:
 article:
 mermaid:
 version: "11" # Mermaid version from CDN
 look: classic  # classic or handDrawn (sketch style)
 lightTheme: default  # Theme for light mode
 darkTheme: neutral  # Theme for dark mode
 securityLevel: strict  # strict (default), loose, antiscript, sandbox
 htmlLabels: true # Enable HTML in labels

hugo.toml:

1
2
3
4
5
6
7


[params.article.mermaid]
 version = "11" # Mermaid version from CDN
 look = "classic" # classic or handDrawn (sketch style)
 lightTheme = "default" # Theme for light mode
 darkTheme = "neutral" # Theme for dark mode
 securityLevel = "strict" # strict (default), loose, antiscript, sandbox
 htmlLabels = true # Enable HTML in labels

Additional Global Options

These optional settings use Mermaid’s defaults when not specified:

hugo.yaml:

1
2
3
4
5
6
7
8
9


params:
 article:
 mermaid:
 maxTextSize: 50000 # Maximum text size (default: 50000)
 maxEdges: 500 # Maximum edges allowed (default: 500)
 fontSize: 16 # Global font size in pixels (default: 16)
 fontFamily: "arial" # Global font family
 curve: "basis" # Line curve: basis, cardinal, linear (default: basis)
 logLevel: 5 # Debug level 0-5, 0=debug, 5=fatal (default: 5)

hugo.toml:

1
2
3
4
5
6
7


[params.article.mermaid]
 maxTextSize = 50000 # Maximum text size (default: 50000)
 maxEdges = 500 # Maximum edges allowed (default: 500)
 fontSize = 16 # Global font size in pixels (default: 16)
 fontFamily = "arial" # Global font family
 curve = "basis" # Line curve: basis, cardinal, linear (default: basis)
 logLevel = 5 # Debug level 0-5, 0=debug, 5=fatal (default: 5)

For diagram-specific options (like flowchart.useMaxWidth), use Mermaid’s init directive directly in your diagram:

1
2
3
4
5


```mermaid
%%{init: {'flowchart': {'useMaxWidth': false}}}%%
flowchart LR
 A --> B
```

Security Note: The default securityLevel: strict is recommended. Set to loose only if you need HTML labels like <br/> in your diagrams.

Available Themes

Theme	Description
`default`	Standard colorful theme
`neutral`	Grayscale, great for printing and dark mode
`dark`	Designed for dark backgrounds
`forest`	Green color palette
`base`	Minimal theme, customizable with themeVariables
`null`	Disable theming entirely

Custom Theme Variables

For full control, use the base theme with custom variables:

hugo.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


params:
 article:
 mermaid:
 lightTheme: base
 darkTheme: base
 lightThemeVariables:
 primaryColor: "#4a90d9"
 primaryTextColor: "#ffffff"
 lineColor: "#333333"
 darkThemeVariables:
 primaryColor: "#6ab0f3"
 primaryTextColor: "#ffffff"
 lineColor: "#cccccc"
 background: "#1a1a2e"

hugo.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


[params.article.mermaid]
 lightTheme = "base"
 darkTheme = "base"

 [params.article.mermaid.lightThemeVariables]
 primaryColor = "#4a90d9"
 primaryTextColor = "#ffffff"
 lineColor = "#333333"

 [params.article.mermaid.darkThemeVariables]
 primaryColor = "#6ab0f3"
 primaryTextColor = "#ffffff"
 lineColor = "#cccccc"
 background = "#1a1a2e"

Common variables: primaryColor, secondaryColor, tertiaryColor, primaryTextColor, lineColor, background, fontFamily

Note: Theme variables only work with the base theme and must use hex color values (e.g., #ff0000).

Diagram Types

Flowchart

Flowcharts are the most common diagram type. Use graph or flowchart with direction indicators:

TD or TB: Top to bottom
BT: Bottom to top
LR: Left to right
RL: Right to left

flowchart LR
 A[Hard edge] -->|Link text| B(Round edge)
 B --> C{Decision}
 C -->|One| D[Result one]
 C -->|Two| E[Result two]

Sequence Diagram

Perfect for showing interactions between components:

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 
prevail!
 John-->>Alice: Great!
 John->>Bob: How about you?
 Bob-->>John: Jolly good!

Class Diagram

Visualize class structures and relationships:

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

State Diagram

Model state machines and transitions:

stateDiagram-v2
 [*] --> Still
 Still --> [*]

 Still --> Moving
 Moving --> Still
 Moving --> Crash
 Crash --> [*]

Entity Relationship Diagram

Document database schemas:

erDiagram
 CUSTOMER ||--o{ ORDER : places
 ORDER ||--|{ LINE-ITEM : contains
 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
 CUSTOMER {
 string name
 string custNumber
 string sector
 }
 ORDER {
 int orderNumber
 string deliveryAddress
 }

Gantt Chart

Plan and track project schedules:

gantt
 title A Gantt Diagram
 dateFormat YYYY-MM-DD
 section Section
 A task :a1, 2024-01-01, 30d
 Another task :after a1, 20d
 section Another
 Task in Another :2024-01-12, 12d
 another task :24d

Pie Chart

Display proportional data:

pie showData
 title Key elements in Product X
 "Calcium" : 42.96
 "Potassium" : 50.05
 "Magnesium" : 10.01
 "Iron" : 5

Git Graph

Visualize Git branching strategies:

gitGraph
 commit
 commit
 branch develop
 checkout develop
 commit
 commit
 checkout main
 merge develop
 commit
 commit

Mindmap

Create hierarchical mindmaps:

mindmap
 root((mindmap))
 Origins
 Long history
 Popularisation
 British popular psychology author Tony Buzan
 Research
 On effectiveness
and features
 On Automatic creation
 Uses
 Creative techniques
 Strategic planning
 Argument mapping
 Tools
 Pen and paper
 Mermaid

Timeline

Display chronological events:

timeline
 title History of Social Media Platform
 2002 : LinkedIn
 2004 : Facebook
 : Google
 2005 : YouTube
 2006 : Twitter

Advanced Features

HTML in Labels

To use HTML in labels, you must set securityLevel: loose in your site config:

hugo.yaml:

1
2
3
4
5


params:
 article:
 mermaid:
 securityLevel: loose
 htmlLabels: true

hugo.toml:

1
2
3


[params.article.mermaid]
 securityLevel = "loose"
 htmlLabels = true

Then you can use HTML tags like <br/> for line breaks:

1
2
3
4


```mermaid
graph TD
 A[Line 1<br/>Line 2] --> B[<b>Bold</b> text]
```

Per-Diagram Theming

Override the theme for a specific diagram using Mermaid’s frontmatter:

1
2
3
4
5


```mermaid
%%{init: {'theme': 'forest'}}%%
graph TD
 A[Start] --> B[End]
```

%%{init: {'theme': 'forest'}}%%
graph TD
 A[Christmas] -->|Get money| B(Go shopping)
 B --> C{Let me think}
 C -->|One| D[Laptop]
 C -->|Two| E[iPhone]
 C -->|Three| F[Car]

Inline Styling with `style`

You can style individual nodes directly within your diagram using the style directive:

1
2
3
4
5
6
7


```mermaid
flowchart LR
 A[Start] --> B[Process] --> C[End]
 style A fill:#4ade80,stroke:#166534,color:#000
 style B fill:#60a5fa,stroke:#1e40af,color:#000
 style C fill:#f87171,stroke:#991b1b,color:#fff
```

Result:

flowchart LR
 A[Start] --> B[Process] --> C[End]
 style A fill:#4ade80,stroke:#166534,color:#000
 style B fill:#60a5fa,stroke:#1e40af,color:#000
 style C fill:#f87171,stroke:#991b1b,color:#fff

Style properties include:

fill - Background color
stroke - Border color
stroke-width - Border thickness
color - Text color
stroke-dasharray - Dashed border (e.g., 5 5)

Styling with CSS Classes

You can define reusable styles with classDef and apply them using :::className:

1
2
3
4
5
6
7


```mermaid
flowchart LR
 A:::success --> B:::info --> C:::warning
 classDef success fill:#4ade80,stroke:#166534,color:#000
 classDef info fill:#60a5fa,stroke:#1e40af,color:#000
 classDef warning fill:#fbbf24,stroke:#92400e,color:#000
```

Result:

flowchart LR
 A:::success --> B:::info --> C:::warning
 classDef success fill:#4ade80,stroke:#166534,color:#000
 classDef info fill:#60a5fa,stroke:#1e40af,color:#000
 classDef warning fill:#fbbf24,stroke:#92400e,color:#000

Subgraphs

Group related nodes together:

flowchart TB
 subgraph one
 a1-->a2
 end
 subgraph two
 b1-->b2
 end
 subgraph three
 c1-->c2
 end
 one --> two
 three --> two
 two --> c2

Theme Switching

This theme automatically detects your site’s light/dark mode preference and adjusts the Mermaid diagram theme accordingly:

Light mode: Uses the default Mermaid theme
Dark mode: Uses the dark Mermaid theme (configurable)

Try toggling the theme switcher to see diagrams update in real-time!

Complex Example

Here’s an example with subgraphs, HTML labels, emojis, and custom styling:

flowchart TD
 subgraph client["👤 Client"]
 A["User Device
192.168.1.10"]
 end

 subgraph cloud["☁️ Cloud Gateway"]
 B["Load Balancer
(SSL Termination)"]
 end

 subgraph server["🖥️ Application Server"]
 C["API Gateway
10.0.0.1"]
 D["Auth Service
10.0.0.2"]
 E["Web Server
10.0.0.3"]
 F["Database
10.0.0.4"]
 end

 A -- "HTTPS Request" --> B
 B -- "Forward
(internal)" --> C
 C -- "Authenticate" --> D
 D -- "Token" --> C
 C -- "Route" --> E
 E --> F

 style client fill:#1a365d,stroke:#2c5282,color:#fff
 style cloud fill:#f6ad55,stroke:#dd6b20,color:#000
 style server fill:#276749,stroke:#22543d,color:#fff

Note: This example requires securityLevel: loose for HTML labels and styling to work.

Known Limitations

Dark Mode Theming

Mermaid.js’s built-in themes have some limitations:

dark theme (default): Best text contrast, but some diagram backgrounds may appear brownish (e.g., Gantt charts)
neutral theme: Better background colors, but some text (labels, legends) may have reduced contrast

For full control, use the base theme with custom variables:

hugo.yaml:

1
2
3
4
5
6
7
8
9


params:
 article:
 mermaid:
 darkTheme: base
 darkThemeVariables:
 primaryColor: "#1f2937"
 primaryTextColor: "#ffffff"
 lineColor: "#9ca3af"
 textColor: "#e5e7eb"

hugo.toml:

1
2
3
4
5
6
7
8


[params.article.mermaid]
 darkTheme = "base"

 [params.article.mermaid.darkThemeVariables]
 primaryColor = "#1f2937"
 primaryTextColor = "#ffffff"
 lineColor = "#9ca3af"
 textColor = "#e5e7eb"

We plan to improve dark mode theming in future updates as Mermaid.js evolves.

Troubleshooting

Diagram not rendering?

Make sure you’re using a fenced code block with mermaid as the language
Check your browser’s console for syntax errors
Verify your Mermaid syntax at Mermaid Live Editor

HTML not working in labels?

HTML in labels requires securityLevel: loose. Update your configuration:

hugo.yaml:

1
2
3
4
5


params:
 article:
 mermaid:
 securityLevel: loose
 htmlLabels: true

hugo.toml:

1
2
3


[params.article.mermaid]
 securityLevel = "loose"
 htmlLabels = true

Warning: Using loose security level allows HTML in diagrams. Only use this if you trust your diagram content.

Syntax errors?

Mermaid is strict about syntax. Common issues:

Missing spaces around arrows
Unclosed brackets or quotes
Invalid node IDs (avoid special characters)

Resources

Mermaid Documentation
Mermaid Live Editor - Test diagrams interactively
Mermaid Syntax Reference

Mermaid on dantas.io

Mermaid Diagrams

About Mermaid.js

Getting Started

Features

Configuration

Additional Global Options

Available Themes

Custom Theme Variables

Diagram Types

Flowchart

Sequence Diagram

Class Diagram

State Diagram

Entity Relationship Diagram

Gantt Chart

Pie Chart

Git Graph

Mindmap

Timeline

Advanced Features

HTML in Labels

Per-Diagram Theming

Inline Styling with style

Styling with CSS Classes

Subgraphs

Theme Switching

Complex Example

Known Limitations

Dark Mode Theming

Troubleshooting

Diagram not rendering?

HTML not working in labels?

Syntax errors?

Resources

Inline Styling with `style`