Simon Willison spotlighted a practical idea: pair Mermaid diagrams with lightweight ASCII so changes are visible in code review and terminals. Here’s a quick, durable workflow you can adopt today.
Mermaid is perfect for rich docs and dashboards, but images don’t diff well. A short ASCII sketch alongside your .mmd source makes architecture updates obvious in PRs and readable over SSH.
Why ASCII still matters
- Reviewable: text diffs highlight what changed without opening images.
- Portable: survives copy/paste, terminals, and email threads.
- Accessible: useful when images are blocked or bandwidth is tight.
- Searchable: grep-able across repos and docs.
A pragmatic workflow that works today
- Author the source in Mermaid (
.mmd) and keep it in your repo. GitHub and GitLab can render Mermaid directly in Markdown—great for READMEs and wikis (GitHub announcement). - Render high-fidelity images in CI using Mermaid CLI for docs and sites:
npm i -D @mermaid-js/mermaid-clithennpx mmdc -i diagrams/flow.mmd -o build/flow.svg(CLI repo). - Add a brief, hand-edited ASCII sketch next to each diagram (e.g.,
diagrams/flow.ascii) to summarize boxes and arrows. Keep it simple—just enough to show changed steps or actors. - Optional: Use a PR bot to propose an ASCII summary from the
.mmdcontent (LLM-generated), but require human review for accuracy and security. - Gate merges with a CI check that re-runs Mermaid rendering and warns when generated assets are stale.
What to include in the ASCII sketch
- Title and scope (e.g., “Checkout flow v2”).
- Key nodes as boxes:
+--- Service A ---+ - Directed edges:
A --> B: eventorA -> B - Only the changed or critical paths—skip decorative layout.
Caveats
- ASCII is a summary, not the source of truth—Mermaid remains canonical.
- Complex layouts rarely translate well; focus ASCII on intent and deltas.
- Keep ASCII close to the
.mmdfile to reduce drift (same folder, same filename stem).
Sources and further reading
- Mermaid documentation: https://mermaid.js.org/
- Mermaid CLI (mmdc): https://github.com/mermaid-js/mermaid-cli
- Context that inspired this tip: Simon Willison on Mermaid + ASCII
Takeaway
Keep Mermaid for fidelity and publishable docs; add a tiny ASCII companion for PRs and terminals. You’ll speed up reviews, reduce ambiguity, and make architecture changes obvious.
Get practical AI + dev tips in your inbox. Subscribe to our free newsletter: theainuggets.com/newsletter
