Mermaid in Markdown

Create diagrams using fenced code blocks:

```mermaid
flowchart TB
    A[Start] --> B[End]
```

Reference Files (Load Only What You Need)

Core Diagrams

Diagram Type	Load this file
Flowchart - processes, workflows	flowchart.md
Sequence - API interactions	sequence.md
Class - OOP structures	class.md
State - lifecycles, FSM	state.md
ERD - database schemas	erd.md
Gantt - project timelines	gantt.md

Charts & Data Visualization

Diagram Type	Load this file
Pie - proportional data	pie.md
Quadrant - priority matrix	quadrant.md
Radar - multi-dimensional	radar.md
XY Chart - line/bar graphs	xychart.md
Sankey - flow quantities	sankey.md
Treemap - hierarchical data	treemap.md

Specialized Diagrams

Diagram Type	Load this file
C4 - architecture (Context/Container/Component)	c4.md
Architecture - cloud/infra	architecture.md
Block - manual layouts	block.md
Mindmap - brainstorming	mindmap.md
Timeline - chronological events	timeline.md
Journey - user workflows	journey.md
GitGraph - branching	gitgraph.md
Kanban - task boards	kanban.md
ZenUML - code-like sequence	zenuml.md
Requirement - SysML	requirement.md
Packet - network protocols	packet.md

Reference & Guides

When you need...	Load this file
Which diagram to use?	selection-guide.md
Layout/width problems	layout.md
Styling and themes	styling.md
Platform compatibility	platforms.md
Core syntax rules	syntax.md
Copy-paste templates	templates.md

Quick Diagram Selection

Scenario	Diagram	Keyword
Database tables	ERD	erDiagram
API calls	Sequence	sequenceDiagram
Process steps	Flowchart	flowchart TB
Status lifecycle	State	stateDiagram-v2
Project schedule	Gantt	gantt
Brainstorm	Mindmap	mindmap
Architecture	Flowchart+subgraphs	flowchart TB
Git workflow	GitGraph	gitGraph
Task board	Kanban	kanban

Essential Patterns (Copy-Paste Ready)

Flowchart with Decision

flowchart TB
    Start[Start] --> Check{Valid?}
    Check -->|Yes| Process[Process]
    Check -->|No| Error[Error]
    Process --> Done[Done]
    Error --> Done

Flowchart with Subgraphs (Architecture)

flowchart TB
    subgraph Frontend
        UI[Web App]
    end
    subgraph Backend
        API[API Server]
        DB[(Database)]
    end
    UI --> API --> DB

ERD with Attributes

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        int id PK
        string name
        string email UK
    }
    ORDER {
        int id PK
        int customer_id FK
        date created_at
    }

Sequence with Activation

sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database
    C->>+A: POST /users
    A->>+D: INSERT user
    D-->>-A: user_id
    A-->>-C: 201 Created

State Machine

stateDiagram-v2
    [*] --> Draft
    Draft --> Pending: Submit
    Pending --> Approved: Approve
    Pending --> Rejected: Reject
    Approved --> [*]
    Rejected --> Draft: Revise

Mindmap

mindmap
    root((Project))
        Backend
            API
            Database
        Frontend
            React
            CSS
        DevOps
            CI/CD
            Monitoring

Critical Rules

1. Use TB direction - LR causes width overflow on letter-size PDF and narrow viewports
2. Wrap "end" - Use [end], (end), or "end" (reserved word)
3. Quote special chars - Text with []{}() needs double quotes: A["text [with] brackets"]
4. Avoid node IDs starting with o/x - A---oB parsed as circle edge; use A--- oB or A---OB
5. Alphanumeric node IDs only - Use A1, userAuth, not user-auth or step.1 (hyphens/dots break parsing)
6. Split large diagrams - Keep under 20 nodes per diagram
7. Test first - Use mermaid.live before committing
8. ASCII labels only - Avoid emoji/Unicode because not all renderers support them
9. Dark theme preferred - Use %%{init: {'theme': 'dark'}}%% for all diagrams; provides color differentiation and consistent appearance
10. No inline styling - Avoid style NodeID fill:#hex lines because themes provide consistent colors across diagrams

Initialization Directives

Control rendering with %%{init: ...}%% at the start of the diagram:

ELK Layout (Complex Diagrams)

For diagrams with many edge crossings or complex layouts:

%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart TB
    A --> B & C & D
    B & C --> E
    D --> E

Theme + Layout Combined

%%{init: {'theme': 'neutral', 'flowchart': {'defaultRenderer': 'elk', 'htmlLabels': false}}}%%
flowchart TB
    A[Start] --> B[Process]

Common Init Options

Option	Values	Use Case
theme	neutral, default, dark, forest	Print: neutral. Dark mode: dark
defaultRenderer	dagre (default), elk	ELK for complex layouts
htmlLabels	true/false	false for markdown in labels
curve	basis, linear, cardinal	Edge curve style

Common Fixes

Problem	Solution
Diagram not rendering	Check for lowercase "end" - capitalize or quote it
Diagram too wide / PDF overflow	Change LR to TB for letter-size output
"Parse error" on node	Quote text containing brackets: ["my [label]"]
Node ID parse error	Use alphanumeric only - no hyphens, dots, or special chars
Unexpected edge style	Node ID starts with o/x - add space or capitalize
Subgraph direction ignored	External connections override - restructure links
GitHub not rendering	Check for unsupported features (ELK, some beta charts)
Edge crossings messy	Add %%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
Emoji/symbols missing	Replace with ASCII text - not all renderers support Unicode
Poor contrast or inconsistent colors	Use %%{init: {'theme': 'dark'}}%% for all diagrams
Inline style declarations	Remove style X fill:#hex lines - use theme directive instead
Platform differences	See platforms.md