mermaid-best-practices

Mermaid Best Practices

Rules for creating Mermaid diagrams that render correctly across Obsidian, GitHub, and standard markdown renderers.

Core principle: Always quote node text. Use stable diagram types. Test before committing.

When to Use

• Creating any Mermaid diagrams in markdown files
• Generating visual artifacts (funnels, processes, architecture)
• Fixing broken or non-rendering diagrams
• Choosing the right diagram type for a use case

Critical Rules

1. Always Quote Node Text

Always wrap node text in double quotes when it contains:

• Non-ASCII characters (Cyrillic, CJK, accented letters)
• Spaces
• Special characters (parentheses, periods, commas)
• Leading digits

%% WRONG
flowchart TD
    A[Market Analysis] --> B[Pick a Niche]

%% CORRECT
flowchart TD
    A["Market Analysis"] --> B["Pick a Niche"]

Safe default: Quote everything. There is zero downside.

2. Avoid Parentheses Inside Nodes

Parentheses () conflict with node shape syntax and cause parse failures.

%% WRONG — parser confuses shape delimiters with text
A(["Step 1 (important)"])

%% CORRECT — use dashes or remove parens
A(["Step 1 — important"])

3. Node Shapes

Syntax	Shape	Example
A["text"]	Rectangle	A["Analysis"]
A("text")	Rounded	A("Decision")
A{"text"}	Diamond (decision)	A{"Condition?"}
A(["text"])	Stadium	A(["Start"])
A[["text"]]	Subroutine	A[["Subprocess"]]
A[("text")]	Cylinder (DB)	A[("Database")]
A(("text"))	Circle	A(("Endpoint"))

4. Subgraph Titles Must Be Quoted

Subgraph labels with spaces or special characters must use the ID["Title"] form:

%% WRONG
subgraph Data Preparation
    A --> B
end

%% CORRECT
subgraph PREP["Data Preparation"]
    A --> B
end

5. Arrow Types

Syntax	Meaning
-->	Arrow
---	Line (no arrowhead)
-.->	Dashed arrow
==>	Thick arrow
--"label"-->	Arrow with label

%% Labels on arrows — quote if non-ASCII or spaces
A -->|"Yes"| B
A -->|"No"| C

Diagram Types

Stable (recommended)

Type	Use Case
flowchart TD/LR	Processes, funnels, workflows
sequenceDiagram	Interactions, API flows
stateDiagram-v2	State machines
gantt	Timelines, project plans
graph TD/LR	Simple graphs
classDiagram	UML class diagrams
erDiagram	Entity-relationship

Experimental (use with caution)

Type	Issues
quadrantChart	May fail in older renderers
mindmap	Limited support
timeline	Unstable rendering
pie	Label encoding issues with non-ASCII

Tip: For SWOT analysis, use flowchart with subgraph instead of quadrantChart.

Templates

Sales Funnel

flowchart TD
    A["Traffic"] --> B["Landing Page"]
    B --> C{"Converts?"}
    C -->|"Yes"| D["Lead"]
    C -->|"No"| E["Retargeting"]
    D --> F["Qualification"]
    F --> G["Deal"]

    style A fill:#E3F2FD
    style G fill:#C8E6C9

Workflow

flowchart LR
    subgraph INPUT["Input"]
        A["Request"]
    end

    subgraph PROCESS["Processing"]
        B["Step 1"]
        C["Step 2"]
        D["Step 3"]
    end

    subgraph OUTPUT["Output"]
        E["Result"]
    end

    A --> B --> C --> D --> E

    style INPUT fill:#FFF3E0
    style PROCESS fill:#E8F5E9
    style OUTPUT fill:#E3F2FD

State Machine

stateDiagram-v2
    [*] --> Draft: Create
    Draft --> Review: Submit
    Review --> Published: Approve
    Review --> Draft: Reject
    Published --> [*]

    note right of Review: Content review

Sequence Diagram

sequenceDiagram
    participant U as User
    participant S as System
    participant D as Database

    U->>S: Request
    S->>D: Query
    D-->>S: Data
    S-->>U: Response

Pre-Commit Checklist

• All node text with non-ASCII characters is quoted
• Subgraph titles use ID["Title"] form
• No raw parentheses inside node text
• Arrow labels are quoted
• Using a stable diagram type
• Tested in target renderer (Obsidian preview / GitHub)

Troubleshooting

"Unsupported markdown: list"

Cause: Markdown syntax (lists, headers) leaked into the mermaid code block. Fix: Ensure all content inside the block is valid Mermaid syntax only.

Diagram Not Rendering

1. Check quotes around non-ASCII text
2. Check subgraph ... end pairing
3. Check arrow syntax
4. Simplify the diagram to isolate the issue

Shows Raw Code Instead of Diagram

Cause: Outdated renderer or missing Mermaid plugin. Fix: Update Obsidian / ensure GitHub has Mermaid support enabled.