Markdown Mermaid

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

Charts & Data Visualization

Specialized Diagrams

Reference & Guides

Quick Diagram Selection

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

Common Fixes

Keep this skill current

When a Mermaid release adds a diagram type, or GitHub, GitLab, VS Code, or Obsidian changes what it renders, update the reference file for that diagram or platform in the same session. Replace the superseded text; do not append a note.