Markdown is great at text, but it falls short with diagrams. You can write a table or a code block, but if you want to show a system architecture, a flow of logic, or a project timeline, you typically reach for a screenshot or an external tool. That's where Mermaid comes in.

What Is Mermaid?

Mermaid.js is a JavaScript-based diagramming library that lets you write diagrams as text using a simple declarative syntax. You write something like:

```mermaid
graph LR
  A[User] --> B[API]
  B --> C[Database]
```

And it renders as an actual diagram. The beauty of Mermaid is that diagrams live in your markdown source — they're version-controlled, diffable, and don't require external tools or image files.

Mermaid is supported natively by GitHub (in README files and issues), GitLab, Notion, Confluence, and an increasing number of markdown editors. But if you're editing locally on a Mac, you need a tool that renders it — and most editors don't.

Basic Mermaid Syntax

Flowcharts

Flowcharts (called graph or flowchart) are the most common Mermaid diagram type. They let you define nodes and the connections between them.

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

Direction options: TD (top-down), LR (left-right), RL (right-left), BT (bottom-top).

Node shapes: [Rectangle], (Rounded), {Diamond/Decision}, ([Pill]), [[Subroutine]], [(Database)].

Sequence Diagrams

Sequence diagrams show interactions between systems or actors over time. Great for documenting API flows, authentication sequences, or user interactions.

```mermaid
sequenceDiagram
  participant Browser
  participant API
  participant DB

  Browser->>API: POST /login
  API->>DB: SELECT user WHERE email=?
  DB-->>API: user record
  API-->>Browser: 200 OK + JWT token
```

The ->> arrow is solid, ->> with -->> is a dashed reply. You can add activate/deactivate blocks to show lifetimes, and Note annotations for clarifications.

Gantt Charts

Gantt charts are perfect for project timelines and sprint planning.

```mermaid
gantt
  title Project Timeline
  dateFormat YYYY-MM-DD
  section Design
    Wireframes       :done,    des1, 2026-01-01, 2026-01-07
    UI mockups       :active,  des2, 2026-01-08, 2026-01-14
  section Development
    Backend API      :         dev1, 2026-01-15, 2026-02-01
    Frontend build   :         dev2, 2026-01-22, 2026-02-10
```

State Diagrams

State diagrams show how a system transitions between states — useful for documenting auth flows, subscription states, or UI state machines.

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Review: submit
  Review --> Published: approve
  Review --> Draft: reject
  Published --> Archived: archive
  Archived --> [*]
```

Pie Charts

For quick data visualisation in documentation:

```mermaid
pie title Tech Stack Usage
  "TypeScript" : 45
  "Swift" : 30
  "Python" : 15
  "Other" : 10
```

Entity Relationship Diagrams

For documenting database schemas:

```mermaid
erDiagram
  USER {
    int id
    string email
    string name
  }
  POST {
    int id
    string title
    int user_id
  }
  USER ||--o{ POST : "writes"
```

Rendering Mermaid in Different Editors

Here's where it gets frustrating: most markdown editors don't support Mermaid out of the box.

GitHub/GitLab: Native support. Push your markdown, diagrams render automatically.

Obsidian: Requires the Mermaid plugin (community plugin, not built-in on older versions). Works well once configured.

VS Code: No native support. You need to install the "Markdown Preview Mermaid Support" extension. Works, but requires manual setup.

Typora: No native Mermaid support as of 2026.

iA Writer: No Mermaid support.

MacDown: No Mermaid support.

Online editors (HackMD, Dillinger): Most support Mermaid, but you're tied to a browser.

Rendering Mermaid Natively with OpenMark

OpenMark renders Mermaid diagrams out of the box — no plugins, no configuration, no internet connection required. Open any .md file that contains a Mermaid code block and it renders inline in the document view.

This works because OpenMark bundles the Mermaid.js library directly in the app. Your diagrams render locally, offline, with the same fidelity as GitHub's renderer.

The workflow is simple:

Write your markdown with Mermaid code blocks (```mermaid)
Open the file in OpenMark (or just have it open while you edit)
Toggle to document view — diagrams appear rendered inline
Toggle back to edit view to change the syntax
Switch back to see the updated diagram

There's no "save and refresh" cycle. The rendering updates automatically.

Tips for Writing Better Mermaid Diagrams

Keep node labels short. Long labels get cramped. Use IDs for the diagram structure and labels for display.

Use subgraphs to organise complex flowcharts. You can wrap groups of nodes in subgraph Name ... end blocks.

Flowchart vs graph: flowchart is the newer syntax with more features. graph still works but flowchart is preferred for new diagrams.

Test incrementally. Mermaid syntax errors are not always obvious. Build your diagram up node by node rather than writing it all at once.

For sequence diagrams, name your participants. Explicitly declaring participants at the top with participant Browser as 🌐 Browser gives you control over order and labels.

Why Mermaid Belongs in Your Workflow

If you write documentation, technical specs, or READMEs, Mermaid diagrams are worth adding to your toolkit. They:

Live in your repository alongside code
Render on GitHub without any extra steps
Can be reviewed in pull requests like any other text change
Work completely offline
Don't require design tools or image exports

The main friction has always been local rendering — knowing what your diagram will look like before you push. A dedicated editor that shows you the rendered output solves that problem entirely.

For more on what features to look for in a markdown editor, see The Best Markdown Editors for Mac in 2026. And if you're using markdown heavily for development work, Markdown for Developers: README Files, Documentation, and More covers the broader ecosystem.

Try Mermaid in OpenMark — download OpenMark from the Mac App Store and open a file with a Mermaid code block. The diagram renders instantly, no setup required.

Download OpenMark →