How to Create Diagrams in Markdown with Mermaid

Technical writing often requires visuals like architecture diagrams, flow charts, and entity relationships. Traditionally you would open a separate tool, draw the diagram, export it as an image, and embed it into your document. Mermaid diagrams in Markdown eliminate that entire workflow. You describe the diagram in plain text, directly inside a fenced code block, and the editor renders it inline.

Quick Answer: Mermaid is a JavaScript library that turns text definitions into SVG diagrams inside Markdown. It supports 10+ diagram types including flowcharts, sequence diagrams, and Gantt charts. Wrap your diagram code in a fenced block tagged mermaid and any compatible editor, including GitHub, GitLab, and edtr.md, renders it automatically.

What Is Mermaid and Why Use It for Diagrams?

Mermaid is a JavaScript library that turns text definitions into SVG diagrams. It supports over a dozen diagram types and is natively supported by GitHub, GitLab, Notion, Obsidian, and editors like edtr.md. GitHub added native Mermaid support in 2022, bringing diagram rendering to millions of repositories without any extra tooling.

The key advantage: diagrams live in your source file. No binary image files to manage, no external tool to keep in sync. When the diagram changes, you edit the text and version control tracks the diff naturally.

Additional benefits of Mermaid over static images:

• Diagrams scale to any screen size because they are SVG vectors
• Text diffs in pull requests show exactly what changed in a diagram
• No broken image links when files are moved or repositories are forked
• Diagrams render in PDF exports with full resolution when using a browser-based printer

How Do You Create a Flowchart in Mermaid?

The most common Mermaid diagram. Use it for process flows, decision trees, and pipelines.

```mermaid
graph TD
  A[User visits page] --> B{Logged in?}
  B -->|Yes| C[Show dashboard]
  B -->|No| D[Show login form]
  D --> E[User submits credentials]
  E --> B
```

TD means top-down. Use LR for left-to-right layouts. Node shapes are controlled by brackets: [] for rectangles, {} for diamonds, (()) for circles, [[]] for subroutines.

Layout direction reference:

Direction	Code	Best For
Top to bottom	TD or TB	Deep decision trees
Left to right	LR	Wide pipelines and flows
Bottom to top	BT	Dependency hierarchies
Right to left	RL	Reverse flows

How Do You Create a Sequence Diagram in Mermaid?

Perfect for documenting API interactions and message flows between services.

```mermaid
sequenceDiagram
  participant Browser
  participant API
  participant DB

  Browser->>API: POST /login
  API->>DB: SELECT user
  DB-->>API: user row
  API-->>Browser: 200 OK + token
```

Solid arrows (->>) indicate requests; dashed arrows (-->>) indicate responses. You can add notes, loops, and alt blocks for conditional flows.

Sequence diagrams are widely used in API documentation because they make the order of operations unambiguous. They are particularly effective in technical documentation with Markdown when describing multi-service architectures.

How Do You Create a Gantt Chart in Mermaid?

Useful for project timelines and release planning.

```mermaid
gantt
  title Release Plan
  dateFormat YYYY-MM-DD
  section Backend
    API design       :a1, 2026-03-01, 7d
    Implementation   :a2, after a1, 14d
  section Frontend
    UI mockups       :b1, 2026-03-01, 5d
    Development      :b2, after b1, 14d
  section QA
    Testing          :c1, after a2, 7d
```

Gantt charts support after dependencies so tasks automatically adjust when their predecessors shift. The dateFormat directive accepts any moment.js-compatible format string.

How Do You Create a Class Diagram in Mermaid?

Describe object-oriented structures with classes, properties, and relationships.

```mermaid
classDiagram
  class User {
    +String name
    +String email
    +login()
    +logout()
  }
  class Post {
    +String title
    +String body
    +publish()
  }
  User "1" --> "*" Post : writes
```

Visibility modifiers follow UML conventions: + for public, - for private, # for protected. Relationship types include association (-->), inheritance (<|--), composition (*--), and aggregation (o--).

How Do You Create a State Diagram in Mermaid?

Model state machines and lifecycle transitions.

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Review : submit
  Review --> Published : approve
  Review --> Draft : request changes
  Published --> [*]
```

State diagrams are especially useful for documenting document workflows, order statuses, or authentication flows where the system must be in exactly one state at a time.

Pie Chart

```mermaid
pie title Browser Market Share
  "Chrome" : 65
  "Safari" : 18
  "Firefox" : 8
  "Edge" : 5
  "Other" : 4
```

What Other Diagram Types Does Mermaid Support?

Beyond the types above, Mermaid supports several additional diagram formats useful in technical and business contexts:

• Entity Relationship (ER) diagrams for database schema visualization
• User Journey diagrams for UX flows and experience mapping
• Git graph diagrams for visualizing branch and merge history
• Mindmap diagrams for hierarchical concept mapping
• Timeline diagrams for chronological event sequences
• Quadrant charts for 2x2 matrix analysis
• Requirement diagrams for systems engineering documentation

Each type uses the same fenced code block syntax with the mermaid language tag.

Tips for Better Mermaid Diagrams

• Keep diagrams focused on one concept per diagram.
• Use meaningful node labels, not single letters.
• Pick the right direction: LR for wide flows, TD for deep ones.
• Use subgraphs to group related nodes in complex flowcharts.
• Test your diagram in a live editor before committing.
• Aim for 5-10 nodes per diagram. Diagrams with more than 15 nodes become hard to read on standard page widths.
• Use consistent naming conventions: either all nouns for nodes or all verb phrases, not a mix.

How to Use Mermaid Diagrams When Exporting to PDF

When your Markdown document contains Mermaid diagrams and you need to export to PDF, browser-based rendering is the recommended approach. In edtr.md, all Mermaid diagrams are converted to inline SVGs before the print dialog opens. The resulting PDF contains crisp, resolution-independent vector graphics with no external image dependencies.

For a full walkthrough of PDF export options and page break control, see the Markdown to PDF export guide.

Using Mermaid in edtr.md

edtr.md renders Mermaid diagrams automatically. Create a fenced code block with the mermaid language tag, type your diagram definition, and the preview pane shows the rendered SVG in real time. When you export to HTML or print to PDF, the SVG is inlined with no external dependencies needed.

Open edtr.md and paste any of the examples above to see them render instantly.