How to Add Mermaid Diagrams to Your Markdown Files

Quick answer

Wrap Mermaid syntax in a fenced code block tagged mermaid, and any Mermaid-aware renderer draws the diagram from that text. No image file, no separate diagramming app. A basic flowchart looks like this:

graph TD; A-->B; A-->C; B-->D; C-->D;

Four nodes, one top-down flowchart: A branches into B and C, and both feed into D. The block itself isn't special — it's the same fenced code blocks you'd use for a snippet of Python or a shell command, just tagged mermaid instead of a language name. Wherever the thing rendering your Markdown understands Mermaid, the fence disappears and a diagram takes its place.

Step-by-step

Write the fence. Open with three backticks and the word mermaid, write your diagram syntax, then close with three backticks. That tag is what tells the renderer to draw a diagram instead of displaying code.

Choose a diagram type and direction. graph TD; starts a top-down flowchart — TD for top-down, LR if you'd rather flow left to right. Mermaid doesn't stop at flowcharts, either. The same fenced-block pattern also covers sequence diagrams, class diagrams, state diagrams, Gantt charts, entity-relationship diagrams, git graphs, and user journey diagrams, each with its own short syntax inside the same mermaid fence.

Define nodes and connections. A-->B; draws an arrow from node A to node B. Chain more lines to build out the shape:

graph TD; Start-->Draft; Draft-->Review; Review-->Publish; Review-->Draft;

Each line is one connection. Mermaid infers the node boxes straight from the labels, so Start, Draft, Review, and Publish become four boxes with arrows between them — no separate step to define shapes.

Check the rendered result. Before leaning on a newer Mermaid feature, confirm what your renderer actually supports. Drop a fenced block containing just the word info:

info

That prints the Mermaid version your current renderer supports, so you're not debugging syntax that isn't available yet in the first place. If your Markdown editor doesn't render Mermaid at all, the Mermaid Live Editor gives you a real-time preview in a browser tab while you get the syntax right, before you commit it to your notes.

Common problems and fixes

Diagram shows as raw text instead of rendering. Two usual causes: the opening fence is missing the mermaid tag (just three backticks with nothing after them), or the tag is misspelled. Check the exact fence, then check that the closing three backticks sit on their own line.

Diagram doesn't render at all, anywhere. Not every Markdown renderer supports Mermaid out of the box. Viewed somewhere that doesn't, the fenced block just looks like a code snippet — still readable, still valid Markdown, just not drawn as a diagram in that particular viewer.

A diagram that used to work now breaks. Newer Mermaid syntax features need a newer renderer version to understand them. Run the info check above before assuming the syntax itself is wrong.

Keeping diagrams as plain text inside your Markdown file is worth the small learning curve. Mermaid exists in the first place because its creator lost a Visio file and wanted diagrams that lived in version control next to the content they described, instead of a binary export that quietly goes out of date. That's the same instinct behind writing technical docs in Markdown generally: keep the source of truth as text you can diff, search, and edit directly — not a file format only one app can open.

Doing this with Carets

Carets is a fast, native notes and code editor for iPhone, iPad, and Mac — Markdown, plain text, and code in one place. A Mermaid diagram is just a fenced code block, and that's exactly what Carets handles well: syntax highlighting makes a mermaid fence visually distinct from the surrounding prose, so a missing tag or an unclosed fence is easy to spot before you save. Notes stay organized into files, projects, and tags, so a diagram-heavy README or a set of workflow docs doesn't get buried among unrelated notes.

One honest limitation: Carets doesn't render Mermaid as a visual diagram inline. It's a fast text editor, not a diagram renderer. Write and organize the Mermaid source in Carets, then view the rendered diagram wherever you publish it — GitHub, for instance. That split works well in practice: keeping your Markdown consistent as plain text is what makes it portable to whichever renderer you use next.

Carets is available for iPhone, iPad, and Mac on the App Store.

Frequently Asked Questions

What is Mermaid in Markdown?

Mermaid is a text-based diagramming syntax you write inside a fenced code block. Instead of drawing a flowchart in a separate app and pasting in an image, you describe the nodes and connections as plain text, and a Mermaid-aware renderer turns that text into a diagram.

Do I need to install anything to use Mermaid?

No. If you're writing somewhere that already renders Mermaid natively, such as GitHub, the diagram just renders when the Markdown is viewed. If your editor or renderer doesn't support it yet, you can still write and read the Mermaid code as plain text, and check it in the Mermaid Live Editor before committing it.

Why does my Mermaid diagram show as plain text instead of a diagram?

Usually a missing or misspelled mermaid language tag on the opening fence, or an unclosed code block. Confirm the block starts with three backticks and the word mermaid, ends with three backticks, and that the renderer you're viewing it in actually supports Mermaid.

What diagram types can Mermaid create besides flowcharts?

Sequence diagrams, class diagrams, state diagrams, Gantt charts, entity-relationship diagrams, git graphs, and user journey diagrams — each with its own short syntax inside the same fenced mermaid code block.

Conclusion

A Mermaid diagram is nothing more than a fenced code block of plain text, drawn as a diagram by whatever renderer supports it. Once graph TD; and A-->B; click, it's a fast way to keep a flowchart or sequence diagram living next to the notes it documents — instead of a pasted-in image that quietly goes stale the next time your process changes.