How to write Mermaid diagrams in Markdown

Mermaid is a JavaScript library that lets you create diagrams and charts using a simple text-based syntax inside Markdown. CodeInk renders Mermaid diagrams in real-time directly in the preview pane — no plugins or external tools required.

To create a Mermaid diagram, use a fenced code block with mermaid as the language identifier:

Mermaid

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

Flowcharts

Flowcharts are the most common Mermaid diagram type. They visualize processes, decision trees, and workflows. Use graph TD for top-down or graph LR for left-right direction.

Mermaid

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[Ship it]
```

Node shapes

[Text] — rectangle
(Text) — rounded rectangle
{{Text}} — rhombus (diamond/decision)
((Text)) — circle
[/Text/] — parallelogram
[[Text]] — subroutine

Arrow types

--> — solid arrow
--- — solid line (no arrow)
-.-> — dotted arrow
==> — thick arrow
-->|Label| — arrow with label

Sequence diagrams

Sequence diagrams show how different parts of a system interact over time. They are ideal for documenting API flows, authentication processes, and message passing.

Mermaid

```mermaid
sequenceDiagram
    participant U as User
    participant C as Client
    participant S as Server
    participant DB as Database

    U->>C: Click login
    C->>S: POST /auth/login
    S->>DB: Query user
    DB-->>S: User record
    S-->>C: JWT token
    C-->>U: Redirect to dashboard
```

Message types

->> — solid line with arrowhead
-->> — dashed line with arrowhead
->>+ — activate participant
-->>- — deactivate participant

Class diagrams

Class diagrams represent the structure of object-oriented code. They show classes, their attributes, methods, and relationships.

Mermaid

```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +fetch()
    }
    class Cat {
        +boolean indoor
        +purr()
    }
    Animal <|-- Dog
    Animal <|-- Cat
```

Relationship types

<|-- — inheritance
*-- — composition
o-- — aggregation
--> — association
..> — dependency

Entity relationship (ER) diagrams

ER diagrams are essential for database design. They show entities, their attributes, and the relationships between them.

Mermaid

```mermaid
erDiagram
    USER ||--o{ POST : writes
    USER {
        string id PK
        string username
        string email
        date created_at
    }
    POST ||--o{ COMMENT : has
    POST {
        string id PK
        string title
        text content
        date published_at
    }
    COMMENT {
        string id PK
        text body
        date created_at
    }
    USER ||--o{ COMMENT : writes
```

Relationship notation

||--|| — one to one
||--o{ — one to many
o{--o{ — many to many
||--o| — one to zero or one

Gantt charts

Gantt charts are used for project planning and scheduling. They show tasks, durations, and dependencies on a timeline.

Mermaid

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Design
    Wireframes       :done, d1, 2026-01-01, 7d
    UI Mockups       :done, d2, after d1, 5d

    section Development
    Frontend         :active, dev1, after d2, 14d
    Backend          :dev2, after d2, 14d
    Integration      :dev3, after dev1, 7d

    section Launch
    Testing          :test, after dev3, 5d
    Deploy           :milestone, after test, 0d
```

Pie charts

Pie charts visualize proportional data with a simple syntax.

Mermaid

```mermaid
pie title Languages Used
    "TypeScript" : 45
    "Python" : 25
    "Rust" : 15
    "Go" : 10
    "Other" : 5
```

State diagrams

State diagrams model the behavior of a system by showing states and transitions.

Mermaid

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Published : Approve
    Review --> Draft : Request changes
    Published --> Archived : Archive
    Archived --> [*]
```

Tips for writing Mermaid diagrams

Start simple — begin with a few nodes and add complexity gradually.
Use descriptive labels — node labels should be clear and concise.
Choose the right direction — TD (top-down) works for hierarchies, LR (left-right) works for flows.
Add comments — use %% for comments inside Mermaid blocks.
Test incrementally — CodeInk renders in real-time, so you can see errors as you type.

All diagram types above are supported in CodeInk with real-time rendering. Open the editor, paste any of these examples, and see them rendered instantly. For a complete Markdown reference, check out our Markdown Cheat Sheet.