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```mermaid
2graph TD
3 A[Start] --> B[Process]
4 B --> C[End]
5```
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:
1params:
2 article:
3 mermaid:
4 version: "11" # Mermaid version from CDN
5 look: classic # classic or handDrawn (sketch style)
6 lightTheme: default # Theme for light mode
7 darkTheme: neutral # Theme for dark mode
8 securityLevel: strict # strict (default), loose, antiscript, sandbox
9 htmlLabels: true # Enable HTML in labels
hugo.toml:
1[params.article.mermaid]
2 version = "11" # Mermaid version from CDN
3 look = "classic" # classic or handDrawn (sketch style)
4 lightTheme = "default" # Theme for light mode
5 darkTheme = "neutral" # Theme for dark mode
6 securityLevel = "strict" # strict (default), loose, antiscript, sandbox
7 htmlLabels = true # Enable HTML in labels
Additional Global Options
These optional settings use Mermaid’s defaults when not specified:
hugo.yaml:
1params:
2 article:
3 mermaid:
4 maxTextSize: 50000 # Maximum text size (default: 50000)
5 maxEdges: 500 # Maximum edges allowed (default: 500)
6 fontSize: 16 # Global font size in pixels (default: 16)
7 fontFamily: "arial" # Global font family
8 curve: "basis" # Line curve: basis, cardinal, linear (default: basis)
9 logLevel: 5 # Debug level 0-5, 0=debug, 5=fatal (default: 5)
hugo.toml:
1[params.article.mermaid]
2 maxTextSize = 50000 # Maximum text size (default: 50000)
3 maxEdges = 500 # Maximum edges allowed (default: 500)
4 fontSize = 16 # Global font size in pixels (default: 16)
5 fontFamily = "arial" # Global font family
6 curve = "basis" # Line curve: basis, cardinal, linear (default: basis)
7 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```mermaid
2%%{init: {'flowchart': {'useMaxWidth': false}}}%%
3flowchart LR
4 A --> B
5```
Security Note: The default
securityLevel: strictis recommended. Set tolooseonly 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:
1params:
2 article:
3 mermaid:
4 lightTheme: base
5 darkTheme: base
6 lightThemeVariables:
7 primaryColor: "#4a90d9"
8 primaryTextColor: "#ffffff"
9 lineColor: "#333333"
10 darkThemeVariables:
11 primaryColor: "#6ab0f3"
12 primaryTextColor: "#ffffff"
13 lineColor: "#cccccc"
14 background: "#1a1a2e"
hugo.toml:
1[params.article.mermaid]
2 lightTheme = "base"
3 darkTheme = "base"
4
5 [params.article.mermaid.lightThemeVariables]
6 primaryColor = "#4a90d9"
7 primaryTextColor = "#ffffff"
8 lineColor = "#333333"
9
10 [params.article.mermaid.darkThemeVariables]
11 primaryColor = "#6ab0f3"
12 primaryTextColor = "#ffffff"
13 lineColor = "#cccccc"
14 background = "#1a1a2e"
Common variables: primaryColor, secondaryColor, tertiaryColor, primaryTextColor, lineColor, background, fontFamily
Note: Theme variables only work with the
basetheme 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:
TDorTB: Top to bottomBT: Bottom to topLR: Left to rightRL: Right to left
1flowchart LR
2 A[Hard edge] -->|Link text| B(Round edge)
3 B --> C{Decision}
4 C -->|One| D[Result one]
5 C -->|Two| E[Result two]
Sequence Diagram
Perfect for showing interactions between components:
1sequenceDiagram
2 participant Alice
3 participant Bob
4 Alice->>John: Hello John, how are you?
5 loop Healthcheck
6 John->>John: Fight against hypochondria
7 end
8 Note right of John: Rational thoughts <br/>prevail!
9 John-->>Alice: Great!
10 John->>Bob: How about you?
11 Bob-->>John: Jolly good!
Class Diagram
Visualize class structures and relationships:
1classDiagram
2 Animal <|-- Duck
3 Animal <|-- Fish
4 Animal <|-- Zebra
5 Animal : +int age
6 Animal : +String gender
7 Animal: +isMammal()
8 Animal: +mate()
9 class Duck{
10 +String beakColor
11 +swim()
12 +quack()
13 }
14 class Fish{
15 -int sizeInFeet
16 -canEat()
17 }
18 class Zebra{
19 +bool is_wild
20 +run()
21 }
State Diagram
Model state machines and transitions:
1stateDiagram-v2
2 [*] --> Still
3 Still --> [*]
4
5 Still --> Moving
6 Moving --> Still
7 Moving --> Crash
8 Crash --> [*]
Entity Relationship Diagram
Document database schemas:
1erDiagram
2 CUSTOMER ||--o{ ORDER : places
3 ORDER ||--|{ LINE-ITEM : contains
4 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
5 CUSTOMER {
6 string name
7 string custNumber
8 string sector
9 }
10 ORDER {
11 int orderNumber
12 string deliveryAddress
13 }
Gantt Chart
Plan and track project schedules:
1gantt
2 title A Gantt Diagram
3 dateFormat YYYY-MM-DD
4 section Section
5 A task :a1, 2024-01-01, 30d
6 Another task :after a1, 20d
7 section Another
8 Task in Another :2024-01-12, 12d
9 another task :24d
Pie Chart
Display proportional data:
1pie showData
2 title Key elements in Product X
3 "Calcium" : 42.96
4 "Potassium" : 50.05
5 "Magnesium" : 10.01
6 "Iron" : 5
Git Graph
Visualize Git branching strategies:
1gitGraph
2 commit
3 commit
4 branch develop
5 checkout develop
6 commit
7 commit
8 checkout main
9 merge develop
10 commit
11 commit
Mindmap
Create hierarchical mindmaps:
1mindmap
2 root((mindmap))
3 Origins
4 Long history
5 Popularisation
6 British popular psychology author Tony Buzan
7 Research
8 On effectiveness<br/>and features
9 On Automatic creation
10 Uses
11 Creative techniques
12 Strategic planning
13 Argument mapping
14 Tools
15 Pen and paper
16 Mermaid
Timeline
Display chronological events:
1timeline
2 title History of Social Media Platform
3 2002 : LinkedIn
4 2004 : Facebook
5 : Google
6 2005 : YouTube
7 2006 : Twitter
Advanced Features
HTML in Labels
To use HTML in labels, you must set securityLevel: loose in your site config:
hugo.yaml:
1params:
2 article:
3 mermaid:
4 securityLevel: loose
5 htmlLabels: true
hugo.toml:
1[params.article.mermaid]
2 securityLevel = "loose"
3 htmlLabels = true
Then you can use HTML tags like <br/> for line breaks:
1```mermaid
2graph TD
3 A[Line 1<br/>Line 2] --> B[<b>Bold</b> text]
4```
Per-Diagram Theming
Override the theme for a specific diagram using Mermaid’s frontmatter:
1```mermaid
2%%{init: {'theme': 'forest'}}%%
3graph TD
4 A[Start] --> B[End]
5```
1%%{init: {'theme': 'forest'}}%%
2graph TD
3 A[Christmas] -->|Get money| B(Go shopping)
4 B --> C{Let me think}
5 C -->|One| D[Laptop]
6 C -->|Two| E[iPhone]
7 C -->|Three| F[Car]
Inline Styling with style
You can style individual nodes directly within your diagram using the style directive:
1```mermaid
2flowchart LR
3 A[Start] --> B[Process] --> C[End]
4 style A fill:#4ade80,stroke:#166534,color:#000
5 style B fill:#60a5fa,stroke:#1e40af,color:#000
6 style C fill:#f87171,stroke:#991b1b,color:#fff
7```
Result:
1flowchart LR
2 A[Start] --> B[Process] --> C[End]
3 style A fill:#4ade80,stroke:#166534,color:#000
4 style B fill:#60a5fa,stroke:#1e40af,color:#000
5 style C fill:#f87171,stroke:#991b1b,color:#fff
Style properties include:
fill- Background colorstroke- Border colorstroke-width- Border thicknesscolor- Text colorstroke-dasharray- Dashed border (e.g.,5 5)
Styling with CSS Classes
You can define reusable styles with classDef and apply them using :::className:
1```mermaid
2flowchart LR
3 A:::success --> B:::info --> C:::warning
4 classDef success fill:#4ade80,stroke:#166534,color:#000
5 classDef info fill:#60a5fa,stroke:#1e40af,color:#000
6 classDef warning fill:#fbbf24,stroke:#92400e,color:#000
7```
Result:
1flowchart LR
2 A:::success --> B:::info --> C:::warning
3 classDef success fill:#4ade80,stroke:#166534,color:#000
4 classDef info fill:#60a5fa,stroke:#1e40af,color:#000
5 classDef warning fill:#fbbf24,stroke:#92400e,color:#000
Subgraphs
Group related nodes together:
1flowchart TB
2 subgraph one
3 a1-->a2
4 end
5 subgraph two
6 b1-->b2
7 end
8 subgraph three
9 c1-->c2
10 end
11 one --> two
12 three --> two
13 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
defaultMermaid theme - Dark mode: Uses the
darkMermaid 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:
1flowchart TD
2 subgraph client["👤 Client"]
3 A["User Device<br/>192.168.1.10"]
4 end
5
6 subgraph cloud["☁️ Cloud Gateway"]
7 B["Load Balancer<br/>(SSL Termination)"]
8 end
9
10 subgraph server["🖥️ Application Server"]
11 C["API Gateway<br/>10.0.0.1"]
12 D["Auth Service<br/>10.0.0.2"]
13 E["Web Server<br/>10.0.0.3"]
14 F["Database<br/>10.0.0.4"]
15 end
16
17 A -- "HTTPS Request" --> B
18 B -- "Forward<br/>(internal)" --> C
19 C -- "Authenticate" --> D
20 D -- "Token" --> C
21 C -- "Route" --> E
22 E --> F
23
24 style client fill:#1a365d,stroke:#2c5282,color:#fff
25 style cloud fill:#f6ad55,stroke:#dd6b20,color:#000
26 style server fill:#276749,stroke:#22543d,color:#fff
Note: This example requires
securityLevel: loosefor HTML labels and styling to work.
Known Limitations
Dark Mode Theming
Mermaid.js’s built-in themes have some limitations:
darktheme (default): Best text contrast, but some diagram backgrounds may appear brownish (e.g., Gantt charts)neutraltheme: Better background colors, but some text (labels, legends) may have reduced contrast
For full control, use the base theme with custom variables:
hugo.yaml:
1params:
2 article:
3 mermaid:
4 darkTheme: base
5 darkThemeVariables:
6 primaryColor: "#1f2937"
7 primaryTextColor: "#ffffff"
8 lineColor: "#9ca3af"
9 textColor: "#e5e7eb"
hugo.toml:
1[params.article.mermaid]
2 darkTheme = "base"
3
4 [params.article.mermaid.darkThemeVariables]
5 primaryColor = "#1f2937"
6 primaryTextColor = "#ffffff"
7 lineColor = "#9ca3af"
8 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
mermaidas 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:
1params:
2 article:
3 mermaid:
4 securityLevel: loose
5 htmlLabels: true
hugo.toml:
1[params.article.mermaid]
2 securityLevel = "loose"
3 htmlLabels = true
Warning: Using
loosesecurity 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
留言评论
期待你的想法评论加载中