3.1 KiB
Mermaid Syntax Standards & Best Practices
This document summarizes the official syntax standards for Mermaid flowcharts, focusing on node labels, quoting rules, and special character handling. It serves as a reference for the markdown_normalizer plugin logic.
1. Node Shapes & Syntax
Mermaid supports various node shapes defined by specific wrapping characters.
| Shape | Syntax | Example |
|---|---|---|
| Rectangle (Default) | id[Label] |
A[Start] |
| Rounded | id(Label) |
B(Process) |
| Stadium (Pill) | id([Label]) |
C([End]) |
| Subroutine | id[[Label]] |
D[[Subroutine]] |
| Cylinder (Database) | id[(Label)] |
E[(Database)] |
| Circle | id((Label)) |
F((Point)) |
| Double Circle | id(((Label))) |
G(((Endpoint))) |
| Asymmetric | id>Label] |
H>Flag] |
| Rhombus (Decision) | id{Label} |
I{Decision} |
| Hexagon | id{{Label}} |
J{{Prepare}} |
| Parallelogram | id[/Label/] |
K[/Input/] |
| Parallelogram Alt | id[\Label\] |
L[\Output\] |
| Trapezoid | id[/Label\] |
M[/Trap/] |
| Trapezoid Alt | id[\Label/] |
N[\TrapAlt/] |
2. Quoting Rules (Critical)
Why Quote?
Quoting node labels is highly recommended and sometimes mandatory to prevent syntax errors.
Mandatory Quoting Scenarios
You MUST enclose labels in double quotes " if they contain:
- Special Characters:
(),[],{},;,", etc. - Keywords: Words like
end,subgraph, etc., if used in specific contexts. - Unicode/Emoji: While often supported without quotes, quoting ensures consistent rendering across different environments.
- Markdown: If you want to use Markdown formatting (bold, italic) inside a label.
Best Practice: Always Quote
To ensure robustness, especially when processing LLM-generated content which may contain unpredictable characters, always enclosing labels in double quotes is the safest strategy.
Examples:
- ❌ Risky:
id(Start: 15:00)(Colon might be interpreted as style separator) - ✅ Safe:
id("Start: 15:00") - ❌ Broken:
id(Func(x))(Nested parentheses break parsing) - ✅ Safe:
id("Func(x)")
3. Escape Characters
Inside a quoted string:
- Double quotes
"must be escaped as\". - HTML entities (e.g.,
#35;for#) can be used.
4. Plugin Logic Verification
The markdown_normalizer plugin implements the following logic:
- Detection: Identifies Mermaid node definitions using a comprehensive regex covering all shapes above.
- Normalization:
- Checks if the label is already quoted.
- If NOT quoted, it wraps the label in double quotes
"". - Escapes any existing double quotes inside the label (
"->\").
- Shape Preservation: The regex captures the specific opening and closing delimiters (e.g.,
((and))) to ensure the node shape is strictly preserved during normalization.
Conclusion: The plugin's behavior of automatically adding quotes to unquoted labels is fully aligned with Mermaid's official best practices for robustness and error prevention.