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 with subgraphs. Use them to split a large flowchart into sections like "Frontend" and "Backend", or into pipeline stages.

```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. Use a sequence diagram for API call flows and authentication handshakes. Participants appear as vertical lifelines. Messages run 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 show the structure of object-oriented systems, such as a data model or a service's core types. They show classes with their attributes, methods, and relationships.

```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 every state and the transitions between them. Order statuses and document approval workflows are typical examples.

```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 the relationships between them. The symbols mark 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 show project schedules. Tasks appear as horizontal bars on a timeline, with duration, dependencies, and parallel work. Use one for a project plan or roadmap.

```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 show branching strategies and version control workflows: commits, branches, merges, and repository history. Each branch gets its own color.

```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"
```

Timeline Diagrams

Timelines show events across periods. Start with the timeline keyword, an optional title, then one line per period with events separated by colons:

```mermaid
timeline
    title Product Launch Timeline
    2024 : Research
         : First prototype
    2025 : Private beta
         : Public beta
    2026 : GA launch
```

Pie Charts

Pie charts show proportions as slices of a circle. Use one when parts make up a whole, like market share or survey results. Keep to 6 slices or fewer.

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

Flowchart Shapes

Each shape has a conventional meaning in flowcharts:

Arrow Types

Arrows indicate flow direction and relationship types:

Sizing Wide Diagrams

Use the Mermaid component with a minWidth prop to keep a wide diagram, like a Gantt chart or a large Git graph, from being squeezed:

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

Click to Expand

Click a diagram to open it full screen on screens 768px and wider. With the keyboard, focus the diagram and press Enter. Close it with Escape, the close button, or a click outside the diagram.

Turn this off for one diagram with the component form and noZoom:

<Mermaid data-no-zoom="true">
graph LR
    A[Request] --> B[Response]
</Mermaid>

Diagrams written as ```mermaid code fences always open full screen.

Styling Tips

• Break a large flow into smaller diagrams.
• Label your arrows to explain transitions.
• Pick one direction: TD (top-down) for tall diagrams, LR (left-right) for wide ones.
• Cap each diagram at 10-15 nodes.

To color a node, use style for one node or classDef for a group:

Jamdesk keeps your colors in dark mode. A fill with no text color gets a label color that Jamdesk picks to read against the fill.

Learn More

See the official Mermaid documentation for the full syntax, including styling, theming, and more diagram types.

What's Next?