65 lines
3.1 KiB
Markdown
65 lines
3.1 KiB
Markdown
|
# 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:
|
||
|
|
1. **Special Characters**: `()`, `[]`, `{}`, `;`, `"`, etc.
|
||
|
|
2. **Keywords**: Words like `end`, `subgraph`, etc., if used in specific contexts.
|
||
|
|
3. **Unicode/Emoji**: While often supported without quotes, quoting ensures consistent rendering across different environments.
|
||
|
|
4. **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:
|
||
|
|
|
||
|
|
1. **Detection**: Identifies Mermaid node definitions using a comprehensive regex covering all shapes above.
|
||
|
|
2. **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 (`"` -> `\"`).
|
||
|
|
3. **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.
|