Mermaid Diagrams

Mermaid is a text-based diagramming tool that renders diagrams from simple text descriptions.

What is Mermaid?

Mermaid allows you to create:

Flowcharts: Process and decision flows
Sequence diagrams: Interaction between systems
Class diagrams: Object-oriented structures
State diagrams: State machines
Entity relationship diagrams: Database schemas
And more...

The key advantage: diagrams are defined in text, making them version-control friendly.

Creating Mermaid Diagrams

In the Editor

Create a code block with the language set to mermaid:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

Viewing the Diagram

Switch to Preview mode to see the rendered diagram.

Mermaid diagrams render in preview mode. In edit mode, you'll see the text syntax.

Diagram Types

Flowcharts

Show processes and decisions:

graph TD
    A[Start] --> B{Is valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
    C --> E[End]
    D --> E

Syntax:

graph TD
    A[Start] --> B{Is valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]

Directions:

TD or TB: Top to bottom
BT: Bottom to top
LR: Left to right
RL: Right to left

Node shapes:

[text]: Rectangle
(text): Rounded rectangle
{text}: Diamond (decision)
((text)): Circle
>text]: Flag

Sequence Diagrams

Show interactions between systems:

sequenceDiagram
    participant User
    participant API
    participant Database
    
    User->>API: Request
    API->>Database: Query
    Database-->>API: Result
    API-->>User: Response

Syntax:

sequenceDiagram
    participant User
    participant API
    
    User->>API: Request
    API-->>User: Response

Arrow types:

->>: Solid line with arrow
-->>: Dashed line with arrow
-x: Solid line with X
--x: Dashed line with X

Class Diagrams

Show class structures:

classDiagram
    class User {
        +String id
        +String name
        +String email
        +getDocuments()
    }
    class Document {
        +String id
        +String title
        +String content
        +save()
    }
    User "1" --> "*" Document : creates

State Diagrams

Show state machines:

stateDiagram-v2
    [*] --> Draft
    Draft --> InReview : Submit
    InReview --> Approved : Approve
    InReview --> Draft : Request Changes
    Approved --> [*]

Entity Relationship Diagrams

Show database relationships:

erDiagram
    USER ||--o{ DOCUMENT : creates
    USER ||--o{ SIGNOFF : provides
    DOCUMENT ||--o{ SIGNOFF : requires
    DOCUMENT ||--o{ COMMENT : has

Gantt Charts

Show project timelines:

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1
    Design     :a1, 2026-01-01, 30d
    Develop    :after a1, 45d
    section Phase 2
    Test       :2026-03-15, 20d
    Deploy     :2026-04-05, 5d

Pie Charts

Show distributions:

pie title Document Types
    "ADR" : 45
    "RFC" : 30
    "Design Doc" : 25

Styling

Node Styling

graph LR
    A[Normal] --> B[Styled]
    style B fill:#f9f,stroke:#333,stroke-width:2px

Class-based Styling

graph TD
    A[Process]:::important --> B[Result]
    
    classDef important fill:#ff0,stroke:#333

Common Examples

API Request Flow

sequenceDiagram
    participant C as Client
    participant A as API Gateway
    participant S as Service
    participant D as Database
    
    C->>A: HTTP Request
    A->>A: Authenticate
    A->>S: Forward Request
    S->>D: Query Data
    D-->>S: Return Data
    S-->>A: Response
    A-->>C: HTTP Response

Document Workflow

stateDiagram-v2
    [*] --> InProgress : Create
    InProgress --> InProgress : Edit
    InProgress --> PendingReview : Request Signoff
    PendingReview --> InProgress : Rejected
    PendingReview --> Accepted : All Approved
    Accepted --> Closed : Archive
    InProgress --> Closed : Cancel
    Closed --> [*]

System Architecture

graph TB
    subgraph Frontend
        UI[Web UI]
    end
    
    subgraph Backend
        API[API Server]
        WS[WebSocket Server]
    end
    
    subgraph Data
        DB[(Database)]
        Cache[(Redis)]
    end
    
    UI --> API
    UI --> WS
    API --> DB
    API --> Cache
    WS --> Cache

Decision Flow

flowchart TD
    A[New Feature Request] --> B{Is it documented?}
    B -->|No| C[Create RFC]
    B -->|Yes| D{Approved?}
    C --> D
    D -->|No| E[Revise]
    E --> D
    D -->|Yes| F[Create Design Doc]
    F --> G[Implement]