Diagrams | Docizr

A diagram in Markdown is created using a fenced code block with a diagram language identifier. The Markdown file contains only the diagram description as plain text; the renderer converts it to a visual diagram at render time. Mermaid is the most widely supported diagram language in Markdown environments.

Syntax

Diagrams use a fenced code block with the language set to mermaid:

MARKDOWN

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do the thing]
    B -->|No| D[Skip it]
    C --> E[End]
    D --> E
```

Output

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do the thing]
    B -->|No| D[Skip it]
    C --> E[End]
    D --> E

Best Practice

Keep diagrams small and focused — a diagram that tries to show everything becomes unreadable. Split complex systems into multiple focused diagrams.
Use meaningful node labels, not single letters or abbreviations. Readers should be able to understand the diagram without reading surrounding text.
Add a short prose description above or below the diagram explaining what it shows and why it matters. Diagrams are a complement to text, not a replacement.
Test rendering in your target environment — Mermaid syntax and supported diagram types vary between platforms and versions.

Mermaid Diagram Types

Mermaid supports a range of diagram types, each with its own syntax:

Type	Identifier	Use For
Flowchart	`graph` or `flowchart`	Processes, decisions, workflows
Sequence diagram	`sequenceDiagram`	Interactions between actors over time
Class diagram	`classDiagram`	Object-oriented structure and relationships
State diagram	`stateDiagram-v2`	State machines and transitions
Entity relationship	`erDiagram`	Database schema and data relationships
Gantt chart	`gantt`	Project timelines and task scheduling
Pie chart	`pie`	Proportional data
Git graph	`gitGraph`	Branching and commit history
Mindmap	`mindmap`	Hierarchical topic exploration
Timeline	`timeline`	Chronological events

Flowchart Direction

The graph or flowchart keyword accepts a direction modifier:

Modifier	Meaning
`TD` or `TB`	Top to bottom
`BT`	Bottom to top
`LR`	Left to right
`RL`	Right to left

Node Shapes

MARKDOWN

```mermaid
flowchart LR
    A[Rectangle]
    B(Rounded)
    C{Diamond}
    D[(Database)]
    E((Circle))
    F>Asymmetric]
```

Syntax	Shape
`[text]`	Rectangle
`(text)`	Rounded rectangle
`{text}`	Diamond (decision)
`[(text)]`	Database cylinder
`((text))`	Circle

Markdown Flavour Support

Not part of any Markdown specification; support depends entirely on the rendering environment.

Flavour Support Detail

Environment	Support	Notes
Original Markdown	No	Not defined in the original spec.
CommonMark	No	Not part of the CommonMark spec.
GitHub Flavored Markdown	Yes	Mermaid diagrams rendered natively in issues, pull requests, and `.md` files since 2022.
Pandoc Markdown	No	Pandoc does not render Mermaid; the block is treated as a fenced code block.

Practical Examples

Document an API authentication flow using a sequence diagram to show the request/response cycle between client, server, and token provider — much clearer than prose alone.

Syntax

MARKDOWN

```mermaid
sequenceDiagram
    Client->>Server: POST /login
    Server->>TokenService: validate credentials
    TokenService-->>Server: token
    Server-->>Client: 200 OK + token
```

Output

sequenceDiagram
    Client->>Server: POST /login
    Server->>TokenService: validate credentials
    TokenService-->>Server: token
    Server-->>Client: 200 OK + token

Explain a CI/CD pipeline with a flowchart showing each stage and the conditions that trigger the next step.

Syntax

MARKDOWN

```mermaid
flowchart LR
    push[Code Push] --> lint[Lint]
    lint -->|pass| test[Tests]
    test -->|pass| build[Build]
    build -->|pass| deploy[Deploy]
    lint -->|fail| stop[❌ Blocked]
    test -->|fail| stop
    build -->|fail| stop
```

Output

flowchart LR
    push[Code Push] --> lint[Lint]
    lint -->|pass| test[Tests]
    test -->|pass| build[Build]
    build -->|pass| deploy[Deploy]
    lint -->|fail| stop[❌ Blocked]
    test -->|fail| stop
    build -->|fail| stop

Sketch a data model in a wiki or README using an entity relationship diagram before writing any code.

Syntax

MARKDOWN

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : included-in
```

Output

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : included-in