Mermaid Diagrams

Write diagrams as text in fenced code blocks. Jamdesk renders them as SVG at build time.

Basic Usage

Use a fenced code block with the mermaid language identifier:

```mermaid
flowchart LR
    A[Start] --> B[Process] --> C[End]
```

Diagram Types

Flowcharts

Direction can be top-down (TD), left-right (LR), bottom-up (BT), or right-left (RL).

```mermaid
flowchart TD
    A[User Request] --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
    C --> E[Response]
    D --> E
```

Subgraphs

Group related nodes together using subgraphs. This helps organize complex flowcharts into logical sections like "Frontend" and "Backend" or different stages of a pipeline.

```mermaid
flowchart TB
    subgraph Frontend
        A[React App] --> B[Components]
    end
    subgraph Backend
        C[API Server] --> D[(Database)]
    end
    B -->|HTTP| C
```

Sequence Diagrams

Sequence diagrams show how components interact over time. They're ideal for documenting API calls, authentication flows, or any communication between services. Participants appear as vertical lifelines, with messages flowing between them.

```mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Database

    Client->>Server: Request
    Server->>Database: Query
    Database-->>Server: Results
    Server-->>Client: Response
```

Class Diagrams

Class diagrams represent the structure of object-oriented systems. Use them to document data models, show relationships between entities, or design system architecture. They display classes with their attributes, methods, and how they relate to each other.

```mermaid
classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }
    class Order {
        +int id
        +Date created
        +addItem()
        +checkout()
    }
    class Item {
        +String name
        +float price
    }
    User "1" --> "*" Order : places
    Order "1" --> "*" Item : contains
```

State Diagrams

State diagrams model the lifecycle of an object or process. They show all possible states and the transitions between them. Use state diagrams to document order statuses, document workflows, or any system with distinct phases.

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Published
    Review --> Draft
    Published --> [*]
```

Entity Relationship Diagrams

ER diagrams document database schemas and data models. They show entities (tables), their attributes (columns), and relationships between them. The symbols indicate cardinality: one-to-one, one-to-many, or many-to-many.

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ITEM : contains
    USER {
        string name
        string email
    }
    ORDER {
        int id
        date created
    }
```

Gantt Charts

Gantt charts visualize project schedules and timelines. Tasks are displayed as horizontal bars across a timeline, showing duration, dependencies, and parallel work. Use them for project planning, sprint documentation, or roadmaps.

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Planning
        Research       :a1, 2024-01-01, 7d
        Design         :a2, after a1, 5d
    section Development
        Backend        :b1, after a2, 14d
        Frontend       :b2, after a2, 14d
    section Launch
        Testing        :c1, after b1, 7d
        Deployment     :c2, after c1, 2d
```

Git Graphs

Git graphs visualize branching strategies and version control workflows. They show commits, branches, merges, and the overall history of a repository. Each branch is color-coded for easy identification.

```mermaid
gitGraph
    commit id: "Initial"
    branch feature
    checkout feature
    commit id: "Add login"
    commit id: "Add auth"
    checkout main
    merge feature id: "v1.0"
    branch release
    checkout release
    commit id: "Prep 1.1"
    checkout main
    branch hotfix
    checkout hotfix
    commit id: "Fix bug"
    checkout main
    merge hotfix id: "v1.0.1"
    checkout release
    commit id: "Final QA"
    checkout main
    merge release id: "v1.1"
```

Pie Charts

Pie charts display proportional data as slices of a circle. Use them to show market share, survey results, resource allocation, or any data where parts make up a whole. Keep slices to 6 or fewer for readability.

```mermaid
pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 10
    "Edge" : 4
    "Other" : 2
```

Flowchart Shapes

Different shapes convey different meanings in flowcharts:

Arrow Types

Arrows indicate flow direction and relationship types:

Sizing Wide Diagrams

For wide diagrams like Gantt charts or complex Git graphs, you can use the Mermaid component directly with a minWidth prop to ensure the diagram doesn't get compressed:

<Mermaid minWidth="700px">
gantt
    title Wide Project Timeline
    ...
</Mermaid>

Styling Tips

For effective diagrams:

• Keep it simple — Break complex flows into multiple smaller diagrams
• Use labels — Add text to arrows to explain transitions
• Consistent direction — Use TD (top-down) for tall diagrams, LR (left-right) for wide ones
• Limit nodes — Aim for 10-15 nodes maximum per diagram for clarity

Learn More

For the complete Mermaid syntax reference, including advanced features like styling, theming, and additional diagram types, see the official Mermaid documentation.

What's Next?