fix: inline stack theme
This commit is contained in:
@@ -0,0 +1,603 @@
|
||||
---
|
||||
author: Hugo Authors
|
||||
title: Mermaid Diagrams
|
||||
date: 2025-12-23
|
||||
description: A comprehensive guide to creating diagrams with Mermaid in Hugo
|
||||
categories:
|
||||
- Themes
|
||||
- Syntax
|
||||
tags:
|
||||
- Mermaid
|
||||
- Diagrams
|
||||
- Markdown
|
||||
---
|
||||
|
||||
This theme supports [Mermaid](https://mermaid.js.org/) diagrams directly in your Markdown content. Mermaid lets you create diagrams and visualizations using text and code.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## About Mermaid.js
|
||||
|
||||
This theme integrates [Mermaid.js](https://mermaid.js.org/) (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](https://mermaid.js.org/intro/syntax-reference.html).
|
||||
|
||||
## Getting Started
|
||||
|
||||
To create a Mermaid diagram, simply use a fenced code block with `mermaid` as the language identifier:
|
||||
|
||||
````markdown
|
||||
```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:**
|
||||
```yaml
|
||||
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:**
|
||||
```toml
|
||||
[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:**
|
||||
```yaml
|
||||
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:**
|
||||
```toml
|
||||
[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:
|
||||
|
||||
````markdown
|
||||
```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:**
|
||||
```yaml
|
||||
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:**
|
||||
```toml
|
||||
[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
|
||||
|
||||
```mermaid
|
||||
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:
|
||||
|
||||
```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!
|
||||
```
|
||||
|
||||
### Class Diagram
|
||||
|
||||
Visualize class structures and relationships:
|
||||
|
||||
```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()
|
||||
}
|
||||
```
|
||||
|
||||
### State Diagram
|
||||
|
||||
Model state machines and transitions:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Still
|
||||
Still --> [*]
|
||||
|
||||
Still --> Moving
|
||||
Moving --> Still
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
```
|
||||
|
||||
### Entity Relationship Diagram
|
||||
|
||||
Document database schemas:
|
||||
|
||||
```mermaid
|
||||
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:
|
||||
|
||||
```mermaid
|
||||
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:
|
||||
|
||||
```mermaid
|
||||
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:
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
commit
|
||||
```
|
||||
|
||||
### Mindmap
|
||||
|
||||
Create hierarchical mindmaps:
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
root((mindmap))
|
||||
Origins
|
||||
Long history
|
||||
Popularisation
|
||||
British popular psychology author Tony Buzan
|
||||
Research
|
||||
On effectiveness<br/>and features
|
||||
On Automatic creation
|
||||
Uses
|
||||
Creative techniques
|
||||
Strategic planning
|
||||
Argument mapping
|
||||
Tools
|
||||
Pen and paper
|
||||
Mermaid
|
||||
```
|
||||
|
||||
### Timeline
|
||||
|
||||
Display chronological events:
|
||||
|
||||
```mermaid
|
||||
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:**
|
||||
```yaml
|
||||
params:
|
||||
article:
|
||||
mermaid:
|
||||
securityLevel: loose
|
||||
htmlLabels: true
|
||||
```
|
||||
|
||||
**hugo.toml:**
|
||||
```toml
|
||||
[params.article.mermaid]
|
||||
securityLevel = "loose"
|
||||
htmlLabels = true
|
||||
```
|
||||
|
||||
Then you can use HTML tags like `<br/>` for line breaks:
|
||||
|
||||
````markdown
|
||||
```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:
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
%%{init: {'theme': 'forest'}}%%
|
||||
graph TD
|
||||
A[Start] --> B[End]
|
||||
```
|
||||
````
|
||||
|
||||
```mermaid
|
||||
%%{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:
|
||||
|
||||
````markdown
|
||||
```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:**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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`:
|
||||
|
||||
````markdown
|
||||
```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:**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### Subgraphs
|
||||
|
||||
Group related nodes together:
|
||||
|
||||
```mermaid
|
||||
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:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph client["👤 Client"]
|
||||
A["User Device<br/>192.168.1.10"]
|
||||
end
|
||||
|
||||
subgraph cloud["☁️ Cloud Gateway"]
|
||||
B["Load Balancer<br/>(SSL Termination)"]
|
||||
end
|
||||
|
||||
subgraph server["🖥️ Application Server"]
|
||||
C["API Gateway<br/>10.0.0.1"]
|
||||
D["Auth Service<br/>10.0.0.2"]
|
||||
E["Web Server<br/>10.0.0.3"]
|
||||
F["Database<br/>10.0.0.4"]
|
||||
end
|
||||
|
||||
A -- "HTTPS Request" --> B
|
||||
B -- "Forward<br/>(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:**
|
||||
```yaml
|
||||
params:
|
||||
article:
|
||||
mermaid:
|
||||
darkTheme: base
|
||||
darkThemeVariables:
|
||||
primaryColor: "#1f2937"
|
||||
primaryTextColor: "#ffffff"
|
||||
lineColor: "#9ca3af"
|
||||
textColor: "#e5e7eb"
|
||||
```
|
||||
|
||||
**hugo.toml:**
|
||||
```toml
|
||||
[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?
|
||||
|
||||
1. Make sure you're using a fenced code block with `mermaid` as the language
|
||||
2. Check your browser's console for syntax errors
|
||||
3. Verify your Mermaid syntax at [Mermaid Live Editor](https://mermaid.live/)
|
||||
|
||||
### HTML not working in labels?
|
||||
|
||||
HTML in labels requires `securityLevel: loose`. Update your configuration:
|
||||
|
||||
**hugo.yaml:**
|
||||
```yaml
|
||||
params:
|
||||
article:
|
||||
mermaid:
|
||||
securityLevel: loose
|
||||
htmlLabels: true
|
||||
```
|
||||
|
||||
**hugo.toml:**
|
||||
```toml
|
||||
[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](https://mermaid.js.org/intro/)
|
||||
- [Mermaid Live Editor](https://mermaid.live/) - Test diagrams interactively
|
||||
- [Mermaid Syntax Reference](https://mermaid.js.org/intro/syntax-reference.html)
|
||||
Reference in New Issue
Block a user