A Markdown Editor With Built-In Mermaid Diagrams for Mac

Mermaid lets you write flowcharts and sequence diagrams as plain text. mdMD renders them right in your markdown, completely offline.

Zack Pennington ·

Mermaid is the de facto standard for diagrams-as-text: you describe a flowchart, sequence diagram, or Gantt chart in a few lines of plain text, and it renders as a proper diagram. GitHub renders Mermaid blocks in READMEs, Notion supports them, and most documentation sites do too.

The catch is editing them. A Mermaid block in your markdown file looks like this:

graph TD
    A[Write markdown] --> B{Mermaid block?}
    B -->|Yes| C[Render diagram]
    B -->|No| D[Render text]

Open that file in most Mac text editors and you’ll see exactly what’s above — the source, not the diagram. So the usual workflow becomes: write the block, copy it into an online editor to check it, tweak, copy back. Or install an editor extension and a preview plugin and hope they agree with each other.

Diagrams render in place

mdMD treats a Mermaid code block as a first-class part of the document. Type the fence, write the diagram definition, and the rendered diagram appears in your document as you type — flowcharts, sequence diagrams, state diagrams, Gantt charts, whatever Mermaid supports. Edit the definition and the diagram updates.

Because rendering happens inline, a README with three diagrams reads like a document with three diagrams, not like a wall of arrows and brackets.

Fully offline, by design

Here’s the part that matters if you work on internal docs: mdMD bundles the Mermaid library inside the app. Rendering a diagram never makes a network request. Not to a CDN, not to an API — the mermaid.js that draws your diagram ships with the app and runs locally.

That means diagrams render on a plane, behind a corporate firewall, and in repositories whose contents aren’t allowed to touch the network. It also means rendering doesn’t slow down or break when some remote service does. (This is consistent with how mdMD handles everything: the app collects no data and your documents never leave your Mac.)

Rendered diagrams are cached, so scrolling back through a long document doesn’t re-render every chart.

The workflow

  1. Open any .md file in mdMD — or press ⌘N and start a new one.
  2. Type / to insert a code block (or type the fence yourself) and mark it mermaid.
  3. Write the diagram. It renders as you go.
  4. Need the raw source? ⌘T splits the view: markdown on the left, rendered document — diagrams included — on the right.

When the document is done, it’s still plain markdown. Push it to GitHub and the same blocks render there. Copy it with ⌘⇧C and mdMD’s rich export carries the content into Notion or Google Docs.

Honest alternatives

If you don’t want a dedicated editor: mermaid.live is the official online playground and great for one-off diagrams, and VS Code renders Mermaid in its markdown preview with an extension. Both work — they’re just not built around the document you’re writing, and both lean on the network or an extension stack to do it.

If you’d rather your diagrams live where your writing does, download mdMD — it’s free, native, and needs macOS 15 Sequoia or later.