Writing on diagrams
Practical notes on diagrams, docs, and developer ergonomics — published weekly.
Which Tools Support Mermaid Natively? A Checked List
GitHub, GitLab, Notion, Obsidian, VS Code and Azure DevOps render Mermaid natively. Confluence, Slack and Google Docs do not. Every row checked against the vendor's own documentation.
Auto-Generate Architecture Diagrams in CI from Your Spec Files
Your architecture diagram is wrong because it's a hand-maintained copy of the system. Here's how to make it a projection instead — generated from files CI already keeps honest.
Diagrams as Code in 2026: Mermaid, PlantUML, D2, Excalidraw — When to Use What
Four diagrams-as-code tools are worth learning in 2026. Each is best at a different job — a comparison, plus the honest tradeoffs nobody puts on the marketing page.
Convert draw.io Files to Production-Ready SVG (Without the Default Look)
draw.io's Export → SVG dialog ships a 400 KB blob of embedded fonts and foreign-object text. The path from cleaner native exports to treating the .drawio XML as source and re-rendering it.
Adding Beautiful Diagrams to Your Docusaurus / VitePress Site
Enabling Mermaid in Docusaurus or VitePress takes ten minutes. Making the diagrams stop looking generic takes another thirty. The whole path — plugin config, theming, and when to swap the renderer.
10 Mermaid Tricks I Wish I'd Known Before Drawing 200 Diagrams
Most Mermaid users plateau after the basics. These 10 tricks — subgraph zones, classDef inheritance, edge label styling, init blocks — pay back every time you open a fenced mermaid block.
How to Beautify and Theme Mermaid Diagrams in Obsidian & VS Code
The default pastel preview undermines the note you're polishing. Two plugins put a themed Mermaid renderer in the same pane — no round-trip to a web tool. Setup for both, plus the per-file options.
Beautify Every Diagram in Your Markdown Docs with One Command
A docs repo has dozens of Mermaid blocks, half on the default pastel theme, some broken. Two commands plus a CI gate render them all to one consistent theme — and keep them that way.
Generate Mermaid from Plain English with AI (CLI Walkthrough)
Most Mermaid friction isn't writing flowcharts — it's remembering syntax for sequence, ER, state, and class diagrams you draw twice a year. Five prompts, five diagrams, one CLI pipe.
Mermaid vs PlantUML in 2026: Which to Pick for Engineering Docs
Mermaid and PlantUML solve the same problem with different trade-offs. Here's a 2026 comparison on syntax, layout quality, diagram coverage, and ecosystem — with a decision rule at the end.
Does Notion Support Mermaid? Yes — 4 Ways to Embed and Theme It
Yes — Notion renders Mermaid natively in code blocks, but with one fixed theme and no overrides. Compare the 4 ways to embed and theme Mermaid in Notion in 2026.
Why Your GitHub README Diagrams Look Amateur (and the 4 Fixes That Take 10 Minutes)
Most README diagrams suffer from the same four defaults. Here's how to fix all of them in under ten minutes — without redrawing anything.
How to Render Mermaid Diagrams as SVG (and Stop Looking Like Every Other README)
A practical guide to rendering Mermaid as SVG — from the official CLI to custom themes, font fixes, dark mode, and the fastest path when you don't want to tune anything.