The Flowchart You Can Diff: How to Keep Diagrams in Your Notes as Plain Text You Own

A diagram you draw on a canvas becomes a picture only its own app can open. A diagram you write — as plain text, in a fenced code block — stays text: it travels with the note, shows its changes line by line in a diff, and any of a hundred renderers can draw it. The format you pick decides who owns the picture.

The text format that won this argument is Mermaid. It is "a JavaScript based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser." ¹ GitHub added native Mermaid rendering on February 14, 2022, so a flowchart written inside a Markdown file simply draws itself in the repo. ¹ The project sits at over 88,000 stars on GitHub. This is not a niche trick. ²

Most people believe a diagram has to live in a drawing app

The default mental model is that a diagram is a thing you draw: you open a canvas, drag boxes, connect arrows, and save. The artifact that comes out is shaped by that act — it is a picture, and the app that drew it is the only thing that fully understands it. So the diagram lives where it was drawn.

There is real comfort in that model, because drawing is how most of us think a diagram is made. You can see the boxes move. You can nudge an arrow until it looks right. The output feels like a finished object, the way a sketch on paper feels finished.

And for some work the canvas is exactly right: hand-drawn whiteboarding, spatial maps, the kind of loose visual thinking where placement carries meaning. The problem is not the canvas. The problem is what happens to the picture after you close the app.

The pivot: a drawn picture is trapped in its own shape

A flattened diagram is the trap. Export your canvas to PNG or JPG and you get a raster image — genuinely binary, un-editable as text, impossible to diff. That is the dead artifact behind every diagram_v12_final_final.png in a downloads folder. ³ The picture survives; the ability to change it does not.

The villain here is the opaque, single-app shape, not any one product. Some canvas formats are not even binary. Excalidraw's file is a clear example: "The Excalidraw data format uses plaintext JSON." ⁴ So the bytes are readable. But a readable file is not the same as a portable diagram. JSON describing canvas coordinates is meaningful mainly to the one app that drew it; it is not a cross-tool diagram standard the way a paragraph of Markdown is a cross-tool document.

So there are two distinct failure modes, and it helps to name them precisely. One is the flattened raster: a PNG with no text left in it at all. The other is the app-specific format, which is text, perhaps, but text only its origin app meaningfully renders or edits. Both leave the picture tied to where it was born.

The argument: write the diagram as text, and it stays yours

Write the diagram instead of drawing it, and the artifact changes character entirely. Mermaid's tagline is the thesis: it "lets you create diagrams and visualizations using text and code." ⁵ The diagram is now source, a few lines of plain text inside a fenced block, and source is the most portable, most diffable, most durable thing a note can hold.

Here is what a flowchart looks like as text. This renders to the same boxes-and-arrows picture a canvas would give you, but it is the six lines below:

flowchart TD
  A[Open the note] --> B{Diagram is text?}
  B -->|Yes| C[Diffs line by line<br/>renders anywhere]
  B -->|No| D[Trapped in<br/>one app's shape]

Figure: The choice that decides ownership. If the diagram is written as plain text, every change shows in a diff and any renderer can draw it; if it is a drawn blob, it stays tied to the one app that made it.

You author it the way you write a code block. As GitHub's documentation puts it: "To create a Mermaid diagram, add Mermaid syntax inside a fenced code block with the mermaid language identifier," and "Diagram rendering is available in GitHub Issues, GitHub Discussions, pull requests, wikis, and Markdown files." ⁶ No image to attach. No canvas to launch. The mechanism is plain: the text is what you keep, and a renderer turns it into the picture on view.

Two payoffs that a drawn diagram cannot give you

The first payoff is the diff. Because the diagram is source, version control treats it like code. As one practitioner guide puts it: "When the diagram changes, you can see the diff in a pull request the same way you see code changes. No binary files, no attachment management." ⁷ You can finally answer what changed in this diagram — line by line, instead of squinting at two PNGs.

The second payoff is reach. One Mermaid source feeds many renderers — "right inside your markdown files, GitHub READMEs, Notion pages, Obsidian notes, VS Code previews, Confluence, and hundreds of other platforms." ⁸ And from that one text format you can draw flowcharts, sequence diagrams, class, state, entity-relationship, Gantt, pie, user-journey, mindmap, and timeline diagrams, among others. ⁵ The same six lines outlive the tool you wrote them in. As the diagrams-as-code shorthand goes: "No more 'diagram_v12_final_final.png'." ³

This is the positive counterpart to a hard truth about Markdown: a file stays portable until you paste in an image, at which point the binary attachment breaks the clean text. A text diagram is the rich visual element that doesn't break portability, because it never stops being text. We made the image-as-trap case in Markdown Is Portable, Until You Add an Image; this is the inversion of it.

It is also the same shape of argument as keeping structured data without a database silo: structure you own, in text you own, instead of a blob in someone's app. [See Your Notes Can Be a Database, Without a Silo.]

Where a freeform canvas still wins — and three other honest limits

Text diagrams give up manual layout, and that is a real loss. Mermaid auto-lays-out the nodes; you do not drag them to pixel positions. When placement is the meaning — a spatial map, a hand-drawn whiteboard, a sketch where where-things-sit matters — a freeform canvas still wins. Use it there, on purpose.

The trade-off is conceded by Mermaid's own users. The person who opened its feature request for manual layout said it plainly: "the diagrams can only be extended/modified to a limited degree," and "The auto layout is handy in some case, but I often find the layout not appealing (e.g. the alignment of nodes)." ⁹

Three more honest caveats, before you commit:

• You still need a renderer to see it. The text is portable forever; the picture is not embedded. The durable win is a plain-text source that many open renderers can draw — not a baked-in image.
• Excalidraw and similar files are not binary hostages. They are plaintext JSON. ⁴ The honest contrast is "cross-tool text standard" versus "one app's format" versus "a flattened PNG," not "text good, everything else binary."
• Mermaid is not vanilla Markdown. It rides inside a fenced Markdown block as its own small language; it is not part of the CommonMark core. The portability you gain is the portability of the source text, not a claim that diagrams are native Markdown.

None of this dents the thesis. It sharpens it. The win is narrow and exact: a diagram you can read, diff, and re-render — kept honest about the one thing it asks you to give up.

What to do tomorrow

Three moves turn a trapped picture into one you own, and none of them needs a new app. Write the diagram as text rather than drawing it. Keep the source rather than the flattened export. Reserve the canvas for the work where placement is the point. The format is the decision; everything else follows from it.

1. Write your next flowchart as Mermaid, a fenced ```mermaid block inside the note, instead of drawing it on a canvas. Six lines of text is the whole diagram.
2. Keep the source, not the export. If a diagram already exists as a PNG, redraw it once in text so future-you can diff it; never let the flattened image be the only copy.
3. Reserve the canvas for the work it's actually best at: spatial, hand-drawn, placement-as-meaning. Match the tool to whether layout carries the point.

The same logic is why exporting your notes should never feel like an escape: if the diagram was text from the start, there is nothing to rescue it from. [See Export Before You're Forced Out.] And it is why notes kept as open Markdown on your own device matter. A Mermaid diagram written in such a note is the same plain text you already own: it travels with the file, works offline, and is not locked inside any app's canvas.

Frequently Asked Questions

The questions below are the ones note-takers actually ask when they have been burned by a dead diagram. The short answer threads through all of them: write the diagram as text, keep the source rather than the export, and reserve the canvas for the work where placement carries the meaning.

How do I keep a diagram in my notes that I can edit and version like text?

Write it as Mermaid inside a fenced code block rather than drawing it on a canvas. GitHub's documentation says to "add Mermaid syntax inside a fenced code block with the mermaid language identifier." ⁶ Because the diagram is now plain text, it diffs line by line and travels with the note like any paragraph.

Does Mermaid render natively in Obsidian, or do I need a plugin?

Mermaid renders from one text source across "GitHub READMEs, Notion pages, Obsidian notes, VS Code previews, Confluence, and hundreds of other platforms." ⁸ The portable thing is the source text inside a ```mermaid block; the renderer differs per editor, so confirm your specific editor's support, but the diagram itself stays plain text everywhere.

Can I version-control a diagram and see its diff in a pull request?

Yes. Because the diagram is source, "you can see the diff in a pull request the same way you see code changes. No binary files, no attachment management." ⁷ You get a real line-by-line history of what changed in the picture, the thing a flattened PNG can never give you.

What diagram types can Mermaid make from plain text?

From one text format Mermaid draws flowcharts, sequence diagrams, class, state, entity-relationship, Gantt, pie, user-journey, mindmap, and timeline diagrams, among others. ⁵ Mermaid's tagline is the summary: it "lets you create diagrams and visualizations using text and code." ⁵ One syntax, many diagram shapes.

When should I NOT use a text diagram, and when is a drawing tool better?

When placement carries the meaning. Mermaid auto-lays-out and you cannot drag nodes to pixel positions; one Mermaid contributor noted "the auto layout is handy in some case, but I often find the layout not appealing." ⁹ For spatial maps, hand-drawn whiteboarding, or sketches where where-things-sit is the point, a freeform canvas still wins.

Is Excalidraw a binary file that traps my diagram?

No, that is a common misconception. "The Excalidraw data format uses plaintext JSON." ⁴ The honest distinction is not text-versus-binary; it is a cross-tool text standard many renderers draw (Mermaid) versus a format only its own app meaningfully renders. The genuinely dead case is a diagram exported to PNG or JPG.

The diagram you can diff is the diagram you still own a year from now. Steph Ango — who has argued the "file over app" case more cleanly than anyone — puts the principle behind it in one line: "Apps are ephemeral, but your files have a chance to last." ¹⁰ A drawn picture is the app. A written one is the file.

To keep your diagrams as the plain text you already own, mnmnote.com lives in your browser.