Creating Mermaid Flowcharts

Overview

Mermaid has strict syntax rules: node identifiers must be simple alphanumeric (a, b, node1), while labels can contain any text. Modern @{ shape: ..., label: "..." } syntax is preferred over legacy shorthand for clarity and reliability.

When to Use

Use this skill when:

• Creating new Mermaid flowchart diagrams
• Encountering parse errors ("Expecting 'SEMI'", syntax errors)
• Converting diagrams from other formats (dot, graphviz)
• Unsure about shape syntax, connection types, or styling
• Need to add colors or classes to nodes

Don't use for:

• Other Mermaid diagram types (sequence, gantt, class diagrams)
• Complex state machines (use stateDiagram instead)

Quick Reference

Common Shapes

Note: Use stadium for start/end nodes (more readable). Use circle for compact diagrams.

See mermaid-flowchart-reference.md for complete shape list.

Connections

Styling

Core Pattern

❌ WRONG - Spaces in identifiers:

graph LR
    "New constraint revealed?" --> "Return to Phase 1"

Error: Identifiers can't have spaces. Parse will fail.

✅ CORRECT - Simple IDs + Labels:

graph LR
    a@{ shape: diam, label: "New constraint revealed?" }
    b@{ shape: rect, label: "Return to Phase 1" }
    a -->\|yes\| b

Implementation

Step 1: Choose Graph Direction

graph TD    ← Top-down (vertical flow)
graph LR    ← Left-right (horizontal flow)

Choose based on flow:

• TD (or TB) = Top-down for sequential processes, workflows
• LR = Left-right for timelines, state transitions
• BT = Bottom-up (rare)
• RL = Right-left (rare)

Step 2: Define Nodes with Modern Syntax

graph TD
    a@{ shape: diam, label: "Your question here?" }
    b@{ shape: rect, label: "Your action here" }

Rules:

• Identifier = simple alphanumeric only (a, b, node1, step2)
• Label = any text in quotes after label:
• Shape = from reference list (diam, rect, circle, stadium, etc.)

Step 3: Connect Nodes

    a -->\|yes\| b
    a -->\|no\| c

Always label decision branches (yes/no, true/false, etc.)

Step 4: Apply Styling (Optional)

    classDef highlight fill:#ffcccc
    classDef success fill:#ccffcc

    b:::highlight
    c:::success

Define classes before applying them. Each node can only have one class applied.

Styling patterns:

• Multiple end nodes: Use separate end nodes when paths have different outcomes; use single end node when all paths converge naturally
• Decision nodes: Keep neutral (no styling) or style based on their context (error flow vs success flow)
• Need composite styles? Create a new class combining properties rather than applying multiple classes

Common Mistakes

Mistake 1: Spaces in Identifiers

Problem:

"My Node" --> "Other Node"

Fix: Use simple IDs with labels:

a@{ shape: rect, label: "My Node" } --> b@{ shape: rect, label: "Other Node" }

Mistake 2: Missing Edge Labels on Decisions

Problem:

decision --> optionA
decision --> optionB

Fix: Label your decision branches:

decision -->\|yes\| optionA
decision -->\|no\| optionB

Mistake 3: Applying Undefined Classes

Problem:

a:::highlight  ← Class never defined

Fix: Define before applying:

classDef highlight fill:#ffcccc
a:::highlight

Mistake 4: Mixing Legacy and Modern Syntax

Problem:

a@{ shape: diam, label: "Modern" }
b{"Legacy"}  ← Inconsistent

Fix: Use modern syntax consistently throughout diagram.

Debugging Checklist

When you get parse errors:

• All identifiers are simple alphanumeric (no spaces, no special chars)
• Modern @{ shape: ..., label: "..." } syntax used consistently
• Decision nodes have labeled edges
• Classes defined before applied
• No trailing semicolons or extra whitespace
• Graph direction specified (LR, TD, etc.)

Real-World Impact

Using modern syntax eliminates 90% of parse errors. Proper identifier naming allows diagrams to render on first attempt in Obsidian without web lookups or trial-and-error debugging.