How to view Mermaid diagrams in Markdown on a Mac

Mermaid is a small text language for diagrams. You write a fenced code block, tag it mermaid, and describe the diagram in lines of text:

```mermaid
flowchart LR
    A[Finder] -->|Space| B(Quick Look)
    B --> C{Extension installed?}
    C -->|Yes| D[Rendered document]
    C -->|No| E[Raw Markdown]
```

GitHub renders that into an actual flowchart. So do GitLab, Notion and a long list of documentation tools. The appeal is obvious: the diagram lives in the file, diffs like text in code review, and does not require anyone to open a drawing app to change an arrow.

Why it stays a code block on your Mac

Mermaid is not part of Markdown. It is a convention layered on top of it — a renderer notices the mermaid language tag on a fence, hands the contents to the Mermaid library, and swaps in the resulting diagram. A renderer that does not know about that convention does the correct and boring thing: renders a code block.

That is why a file looking perfect on GitHub looks half-finished locally. Most Mac Markdown apps implement CommonMark or GitHub Flavored Markdown faithfully and stop there. The Markdown around the diagram is right; the diagram is source.

Why this matters more than it used to

Mermaid used to be a niche thing that documentation authors opted into. It is now something that appears in your files whether or not you asked: coding agents produce it constantly. Ask for an architecture summary, a migration plan or a sequence of calls and you very often get a mermaid fence back, because it is the format that survives being written as text.

Which inverts the problem. The diagram is no longer decoration on a document you wrote — it is frequently the densest part of a document someone else generated for you, and reading it as source means reading the least useful representation of it.

Getting it rendered locally

Three approaches, with real differences:

A viewer with Mermaid bundled. The diagram renders when you open the file, offline, with no setup. Check that it is genuinely bundled rather than loaded from a CDN — a viewer fetching Mermaid from the network renders nothing on a plane, and sends a request every time you open a document.
An editor extension. VS Code has extensions that add Mermaid to its Markdown preview. Good if you live in the editor already, irrelevant if you are reading a file you have no project for.
The Mermaid CLI. mmdc renders a diagram to SVG or PNG from the command line. Right for build pipelines and publishing; far too slow a loop for reading a document once.

The browser-based Mermaid Live Editor is excellent for authoring and debugging a diagram that will not parse — but it means pasting the contents of a local file into a web app, which is worth a moment's thought for anything from work.

Diagrams in Quick Look

A Quick Look preview can render Mermaid, and it is a good fit: a generated plan or architecture note is usually a glance-and-move-on document, and the diagram is the part you actually want to see.

It does depend on the extension rendering diagrams without a network round-trip — a preview is meant to appear instantly, and a preview surface is a bad place to be waiting on a request. If Space gives you a rendered document but the diagram is still a grey code block, the extension simply does not do Mermaid; that is a capability difference, not something to troubleshoot.

When a diagram does not render anywhere

Sometimes the problem is the diagram, not the viewer. Mermaid is strict, and a syntax error means the whole block fails rather than rendering partially. Worth checking:

The fence is tagged exactly mermaid, lowercase, with nothing after it.
The first line names a valid diagram type — flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie.
Node labels containing brackets, quotes or parentheses are quoted. This is the single most common parse failure, and it is why a diagram from a generated document sometimes breaks while your hand-written ones never do.
The renderer is new enough for the diagram type. Newer types fail on older Mermaid versions, which is also why something rendering on GitHub may not render in an older local tool.

nicemd

nicemd renders Mermaid in both the app window and the Quick Look preview, with the Mermaid runtime bundled in the app rather than fetched — diagrams appear offline and no request leaves your Mac. KaTeX math and syntax highlighting work the same way. Reading and Quick Look are free.