@diagram Blocks

Create flowcharts, sequence diagrams, Gantt charts, and mind maps using Mermaid or Graphviz.

Quick Example

@diagram {
  type: "flowchart";
  engine: "mermaid";
  title: "User Login Flow";
  code: "graph TD
    A[Start] --> B{Valid User?}
    B -->|Yes| C[Dashboard]
    B -->|No| D[Error Page]
    D --> A";
}

Diagram Types

Flowchart

Visualize processes and decision flows.

@diagram {
  type: "flowchart";
  engine: "mermaid";
  title: "Order Processing";
  code: "graph LR
    A[Order] --> B{In Stock?}
    B -->|Yes| C[Ship]
    B -->|No| D[Backorder]
    C --> E[Complete]
    D --> E";
}

Supported directions: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)

Sequence Diagram

Show interactions between actors over time.

@diagram {
  type: "sequence";
  engine: "mermaid";
  title: "API Authentication";
  code: "sequenceDiagram
    Client->>API: Request Token
    API->>Database: Validate User
    Database-->>API: User Valid
    API-->>Client: Return Token";
}

Gantt Chart

Project timelines and task dependencies.

@diagram {
  type: "gantt";
  engine: "mermaid";
  title: "Project Timeline";
  code: "gantt
    title Development Schedule
    section Phase 1
    Design       :a1, 2024-01-01, 30d
    Development  :a2, after a1, 45d
    section Phase 2
    Testing      :a3, after a2, 20d
    Deployment   :a4, after a3, 10d";
}

Mind Map

Organize ideas hierarchically.

@diagram {
  type: "mindmap";
  engine: "mermaid";
  title: "Product Features";
  code: "mindmap
    root((Product))
      Features
        Core
        Advanced
      Users
        Free
        Premium
      Support
        Docs
        Community";
}

Rendering Engines

Mermaid (Default)

Modern, easy-to-use syntax with great support for flowcharts, sequences, Gantt, and more.

✅ Flowcharts

✅ Sequence diagrams

✅ Gantt charts

✅ Mind maps

✅ Simple syntax

Graphviz

Powerful graph visualization with DOT language. Best for complex network diagrams.

✅ Directed graphs

✅ Undirected graphs

✅ Complex layouts

✅ Network diagrams

✅ Advanced control

Graphviz Example:

@diagram {
  type: "flowchart";
  engine: "graphviz";
  title: "System Architecture";
  code: "digraph G {
    rankdir=LR;
    node [shape=box];
    Client -> LoadBalancer;
    LoadBalancer -> Server1;
    LoadBalancer -> Server2;
    Server1 -> Database;
    Server2 -> Database;
  }";
}

Properties

type (required)

Diagram type: flowchart, sequence, gantt, mindmap

engine (required)

Rendering engine: mermaid (default), graphviz

title (optional)

Diagram title/caption

code (required)

Diagram definition in Mermaid or Graphviz syntax

Mermaid Syntax Reference

Flowchart Nodes:

A[Rectangle]

B(Round edges)

C((Circle))

D{Diamond}

E[/Parallelogram/]

Flowchart Arrows:

A -> B (solid)

A -.-> B (dotted)

A ==> B (thick)

A -> |text| B (labeled)

Learn more: Mermaid Documentation

How Diagrams Render

PDF

Rendered using Mermaid.js or Graphviz with high quality SVG output.

DOCX

Diagram code displayed as preformatted text for reference.

PPTX

Diagram code shown on slides with monospace formatting.

Best Practices

✅ Keep it Simple

Complex diagrams with many nodes can be hard to read. Break into multiple diagrams if needed.

✅ Use Descriptive Labels

Label nodes and edges clearly so the diagram is self-explanatory.

✅ Add Titles

Always include a title to provide context for the diagram.

⚠️ Test Your Syntax

Use the playground or Mermaid Live Editor to validate diagram syntax before adding to documents.

Try It Yourself

Test @diagram blocks in the interactive playground:

Open Playground →

← Previous: @chart Blocks Next: @code Blocks →