Mermaid Diagrams

Build a diagram with Insert Diagram, or write Mermaid source directly in a fenced code block with the mermaid language tag.

Table of Contents

Insert or Edit a Diagram

Choose Insert Diagram in the editing toolbar, then:

Select Flowchart, Sequence, Class, State, Entity Relationship, Gantt, Mindmap, Pie, User Journey, Git Graph, Timeline, or Kanban as a starting template.
Edit the Mermaid source.
Check the live preview and correct any reported syntax error.
Choose Insert Diagram when the preview is ready.

To update an existing diagram, place the editor cursor anywhere inside its Mermaid fence and choose Insert Diagram. The modal opens as Edit Diagram, loads the complete block, and replaces it when you choose Update Diagram.

You can also open Insert Diagram from the command palette. The templates are starting points, not a limit on the Mermaid formats MDash can render. Choose View Mermaid Guide in the modal whenever you need this reference in a separate documentation tab.

Diagram Structure

The first line inside the fence selects the diagram type. The remaining lines define nodes, relationships, labels, or data:

Mermaid Source

```mermaid
flowchart LR
  source["Markdown Source"] --> preview["Live Preview"]
```

Rendered Result

flowchart LR
  source["Markdown Source"] --> preview["Live Preview"]

Use stable short identifiers such as source and put readable text inside brackets or quotes. Quoted labels are the safest choice when text contains spaces, punctuation, or parentheses.

Indentation improves readability, even for diagram types where it is not strictly required. Keep one relationship or declaration per line so syntax errors are easier to locate.

Available Diagram Types

Common choices include flowcharts, sequence diagrams, class diagrams, state diagrams, entity relationship diagrams, user journeys, Gantt charts, pie charts, Git graphs, mindmaps, timelines, and Kanban boards.

The bundled Mermaid release also supports specialized formats such as quadrant and XY charts, requirement and architecture diagrams, Sankey diagrams, block and packet diagrams, C4 diagrams, radar charts, treemaps, Venn diagrams, Ishikawa diagrams, event modeling, tree views, and Wardley maps. Formats marked -beta by Mermaid can change between releases. Check the inline preview when using a newer diagram type.

Flowchart

```mermaid
graph TD
  A[Draft] --> B{Ready?}
  B -->|Yes| C[Publish]
  B -->|No| D[Revise]
  D --> A
```

graph TD
  A[Draft] --> B{Ready?}
  B -->|Yes| C[Publish]
  B -->|No| D[Revise]
  D --> A

Use TD for top-to-bottom layouts and LR for left-to-right layouts.

Shapes, Labels, and Subgraphs

flowchart LR
  start([Start]) --> choice{Ready?}
  choice -->|Yes| publish[Publish]
  choice -->|No| revise[Revise]

  subgraph Review
    revise --> choice
  end

Common flowchart forms include [Rectangle], (Rounded), {Decision}, and ([Terminal]). Edge labels use -->|Label|.

Sequence Diagram

sequenceDiagram
  participant T as Traveler
  participant B as Booking Service
  participant A as Airline
  T->>B: Search for a flight
  B->>A: Request availability
  A-->>B: Return available seats
  B-->>T: Show matching flights

Class Diagram

classDiagram
  class LibraryItem {
    +String title
    +Boolean available
  }
  class Book {
    +String author
    +String isbn
  }
  class Magazine {
    +Number issue
  }
  LibraryItem <|-- Book
  LibraryItem <|-- Magazine

State Diagram

stateDiagram-v2
  [*] --> Open
  Open --> Investigating : Assign
  Investigating --> Waiting : Request Information
  Waiting --> Investigating : Reply Received
  Investigating --> Resolved : Fix Confirmed
  Resolved --> [*]

ER Diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : appears_in
  PRODUCT {
    string id
    string name
    decimal price
  }

Pie Chart

pie title Monthly Household Budget
  "Housing" : 40
  "Food" : 25
  "Transport" : 15
  "Savings" : 20

Gantt Chart

gantt
  title Community Festival Plan
  dateFormat YYYY-MM-DD
  section Preparation
  Confirm Venue     :done, 2026-07-01, 5d
  Book Performers   :active, 2026-07-06, 7d
  Recruit Volunteers :2026-07-13, 6d
  section Event
  Final Setup       :2026-07-20, 3d

Mindmap

mindmap
  root((Learn Spanish))
    Vocabulary
      Travel
      Food
    Practice
      Conversation
      Listening
    Review
      Flashcards
      Weekly Quiz

User Journey

journey
  title Visiting a Museum
  section Arrival
    Find the Entrance: 4: Visitor
    Buy a Ticket: 3: Visitor, Staff
  section Explore
    Follow the Map: 4: Visitor
    Join a Guided Tour: 5: Visitor, Guide
  section Finish
    Visit the Museum Shop: 4: Visitor

Git Graph

gitGraph
  commit id: "Initial Draft"
  branch review
  checkout review
  commit id: "Technical Review"
  commit id: "Apply Feedback"
  checkout main
  merge review id: "Approve"
  commit id: "Publish" tag: "v1.0"

Timeline

timeline
  title Urban Garden Project
  2026-03 : Prepare the Soil
  2026-04 : Plant Spring Crops
          : Install Irrigation
  2026-06 : First Harvest
  2026-09 : Autumn Planting

Kanban Board

kanban
  backlog[Backlog]
    paint[Choose Paint Colors]
    lighting[Plan Lighting]
  active[In Progress]
    cabinets[Install Cabinets]@{ assigned: 'Carpenter', priority: 'High' }
  review[Review]
    inspection[Electrical Inspection]@{ assigned: 'Inspector' }
  done[Done]
    flooring[Replace Flooring]

Tips

Start with a template when you are learning a diagram type.
Check the inline preview before inserting a complex diagram.
Diagrams adapt to Light and Dark themes.
Left-to-right layouts often work better for wide diagrams.
Break a complex diagram into smaller diagrams when labels become difficult to read.

For slide-specific layout advice, see Presentation Mode. For color and direction behavior, see Themes and Direction.

Accessibility and Exports

Introduce a diagram with a short sentence that explains its purpose. Important conclusions should also appear in nearby prose because a dense visual can be difficult for screen readers or readers with low vision.

Keep labels concise and use a clear direction. Do not rely on color alone to distinguish states or relationships.

Give a diagram an accessible title and description in its Mermaid source:

Mermaid Source

```mermaid
flowchart LR
  accTitle: Documentation review workflow
  accDescr: A draft moves to review, then either returns for revision or proceeds to publication.
  draft[Draft] --> review{Approved?}
  review -->|No| draft
  review -->|Yes| publish[Publish]
```

Rendered Result

flowchart LR
  accTitle: Documentation review workflow
  accDescr: A draft moves to review, then either returns for revision or proceeds to publication.
  draft[Draft] --> review{Approved?}
  review -->|No| draft
  review -->|Yes| publish[Publish]

Use View Source on a rendered diagram to inspect or copy the Mermaid definition without leaving Preview.

HTML, PDF, presentation, and shared-view rendering prepare Mermaid diagrams before producing the final output. Review complex diagrams in the target format because page width, fonts, and theme colors can change line wrapping.

Errors and Limitations

An invalid diagram displays an inline Mermaid error instead of breaking the rest of the document. Check the first reported line, diagram type, indentation, and punctuation.

MDash uses Mermaid's strict security mode. Diagram source is treated as document content, and unsafe interactive markup is not trusted.

Complex diagrams can still take time to lay out. Prefer several focused diagrams over one very large graph.

Mermaid Diagrams

Insert or Edit a Diagram

Diagram Structure

Available Diagram Types

Flowchart

Shapes, Labels, and Subgraphs

Sequence Diagram

Class Diagram

State Diagram

ER Diagram

Pie Chart

Gantt Chart

Mindmap

User Journey

Git Graph

Timeline

Kanban Board

Tips

Accessibility and Exports

Errors and Limitations

Related Guides