This skill should be used when the user asks to "create a mermaid diagram", "fix mermaid error", "mermaid syntax error", "diagram not rendering", "flowchart not working", "sequence diagram broken", "escape special characters in mermaid", or mentions "mermaid", "flowchart", "sequence diagram", "class diagram", "state diagram", "ER diagram", "gantt chart". Prevents common syntax errors with special characters, reserved words, escaping rules, and provides v11 syntax support.
This skill should be used when the user asks to "create a mermaid diagram", "fix mermaid error", "mermaid syntax error", "diagram not rendering", "flowchart not working", "sequence diagram broken", "escape special characters in mermaid", or mentions "mermaid", "flowchart", "sequence diagram", "class diagram", "state diagram", "ER diagram", "gantt chart". Prevents common syntax errors with special characters, reserved words, escaping rules, and provides v11 syntax support.
version
1.5.0
Mermaid Diagram Syntax Guide
Comprehensive syntax reference for generating error-free Mermaid diagrams. Prevents common mistakes and supports Mermaid v11 features including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, and more.
Multiple reserved words break diagrams. Use quoted labels with safe IDs:
flowchart LR
node1["end"] %% Safe: quoted with different ID
node2["default"] %% Safe: "default" is also reserved
node3["End"] %% Safe: capitalized
All reserved words (use quoted labels):
end, default
style, linkStyle, classDef, class
call, href, click, interpolate
Pattern:safeId["reserved word text"] instead of reserved[text]
3. Node ID Starting Characters
Nodes starting with o or x create unintended edge types:
flowchart LR
orderNode[Order] %% Good: full word
oNode[O-Node] %% Bad: might create circle edge
Solution: Use descriptive IDs, avoid single letters o or x at start.
4. HTML Entity Codes for Semicolons
In sequence diagrams, semicolons define line breaks. Use #59; for literal semicolons:
sequenceDiagram
A->>B: Value#59; Key#59; Data
5. Comments Must Use %%
Single % breaks diagrams. Always use %%:
flowchart LR
%% This is a valid comment
A --> B
6. Subgraph with HTML Tags
Wrap subgraph titles containing <br/> in quotes:
flowchart TB
subgraph "Title with<br/>line break"
A --> B
end
7. Style Property Escaping
Escape commas in stroke-dasharray with backslash:
flowchart LR
A --> B
linkStyle 0 stroke-dasharray: 5\,5
8. Frontmatter Must Be First Line
The --- for frontmatter MUST be the only content on line 1:
---
config:
theme: forest
---
flowchart LR
A --> B
Wrong: Any whitespace or content before --- breaks the diagram.
9. Mindmap < Character Bug
In mindmaps, < renders as <. Use words instead:
mindmap
root((Comparison))
Less than 10 %% Instead of "< 10"
Greater than 5 %% Instead of "> 5"
10. Class Diagram Colon Limitations
Colons in class member types are tricky. Use return type syntax:
classDiagram
class MyClass {
+getData() Map~String, Object~
}
Note: Complex generic types with colons may not render correctly.
11. Nested Subgraph Linking Bug
Linking to both parent AND nested subgraph causes syntax error:
flowchart LR
%% BAD: linking to both system AND sub-system breaks
%% A --> system
%% B --> sub-system
%% GOOD: link to nodes inside, not subgraph itself
A --> service1
B --> service2
subgraph system
subgraph sub-system
service1
service2
end
end
Workaround: Link to nodes inside subgraphs, not the subgraph ID itself.
12. Subgraph Direction Inheritance
If subgraph nodes link to outside, direction is ignored (inherits parent):
flowchart LR
A --> B
subgraph sub [My Subgraph]
direction TB %% Ignored if C links outside!
C --> D
end
B --> C %% This external link forces LR direction
Rule: Subgraph direction only works if all nodes stay internal.
13. v11 Arrowless Edges Bug (v11.0-11.4)
In Mermaid v11.0 to v11.4.x, the --- (line without arrow) syntax is broken and shows arrows:
flowchart LR
%% BROKEN in v11.0-11.4: shows arrow instead of line
A --- B
%% Workaround: use explicit arrow and style
C --> D
linkStyle 0 stroke:#333,stroke-width:2px
Fix: Upgrade to Mermaid v11.5.0 or later.
14. v11 Markdown-by-Default Breaking Change
In v11, ALL node labels render as Markdown by default (breaking change from v10):
flowchart LR
%% v10: plain text, v11: renders as Markdown
A[**bold** and _italic_]
%% Problem: underscores in text become italic
B["file_name_here"] %% Use quotes to prevent issues
Note: Only bold (**) and italic (_ or *) are supported. Inline code with backticks may not work.
15. Configuration Limits (Secure Settings)
maxTextSize (default: 50,000 chars) and maxEdges (default: 500) are secure settings that CANNOT be set via frontmatter:
---
config:
maxTextSize: 100000 %% IGNORED! Secure setting
---
flowchart LR
A --> B
Workaround: These must be set via mermaid.initialize() in JavaScript, not in diagram config.
16. linkStyle Hex Color as Last Attribute Bug
Hex color as the LAST attribute in linkStyle causes parsing error:
flowchart LR
A --> B
%% BAD: hex color as last attribute
%% linkStyle 0 stroke-width:4px,stroke:#FF69B4
%% GOOD: hex color NOT last, or use color name
linkStyle 0 stroke:#FF69B4,stroke-width:4px
%% OR: linkStyle 0 stroke-width:4px,stroke:hotpink
Workaround: Put hex color before other attributes, or use CSS color names.
17. Class Diagram Namespace Limitations
Relationships and notes MUST be defined OUTSIDE namespace blocks:
classDiagram
namespace MyPackage {
class ClassA
class ClassB
}
%% Relationships OUTSIDE namespace block
ClassA --> ClassB
note for ClassA "This note is outside namespace"
Limitation: Nested namespaces not supported. Use flat structure.
18. Architecture Diagram Label Characters
Architecture node labels only support [a-zA-Z0-9_ ]. Hyphens and special chars break:
architecture-beta
%% BAD: service db[Cloud-Name] (hyphen breaks)
%% GOOD: use underscore or spaces
service db(database)[Cloud_Name]
Mermaid v11 New Features
Hand-Drawn Look
%%{init: {"look": "handDrawn"}}%%
flowchart LR
A[Sketchy] --> B[Style]
Bidirectional Arrows (Sequence)
sequenceDiagram
A <<->> B: Bidirectional
A <<-->> B: Bidirectional dotted
Configuration Directive
%%{init: {
"theme": "dark",
"flowchart": {"curve": "linear"}
}}%%
flowchart LR
A --> B
Diagram Type Quick Reference
Flowchart Direction
Syntax
Direction
flowchart TB
Top to Bottom
flowchart TD
Top Down (same as TB)
flowchart BT
Bottom to Top
flowchart LR
Left to Right
flowchart RL
Right to Left
Node Shapes
Syntax
Shape
A[text]
Rectangle
A(text)
Rounded rectangle
A([text])
Stadium
A[[text]]
Subroutine
A[(text)]
Cylinder (database)
A((text))
Circle
A{text}
Diamond
A{{text}}
Hexagon
A>text]
Asymmetric
Edge Types
Syntax
Type
A --> B
Arrow
A --- B
Line (no arrow)
A -.- B
Dotted line
A ==> B
Thick arrow
A -.-> B
Dotted arrow
A --text--> B
Arrow with text
A -- text --- B
Line with text
Subgraph Syntax
flowchart TB
subgraph GroupName["Display Title"]
direction LR
A --> B
end
C --> GroupName
Sequence Diagram Essentials
Message Arrow Types
Syntax
Description
A->B
Solid line, no arrow
A-->B
Dotted line, no arrow
A->>B
Solid line, arrowhead
A-->>B
Dotted line, arrowhead
A-xB
Solid line, cross end
A-)B
Solid line, open arrow (async)
Participant Definition
sequenceDiagram
participant A as Alice
actor B as Bob
A->>B: Hello
Activation
sequenceDiagram
A->>+B: Request
B-->>-A: Response
Or explicit:
sequenceDiagram
A->>B: Request
activate B
B-->>A: Response
deactivate B
Control Flow
sequenceDiagram
alt Success
A->>B: OK
else Failure
A->>B: Error
end
opt Optional
A->>B: Maybe
end
loop Every minute
A->>B: Ping
end
par Parallel
A->>B: Task1
and
A->>C: Task2
end
Notes
sequenceDiagram
Note right of A: Single line note
Note over A,B: Spanning note
Class Diagram Essentials
Class Definition
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
