Writing on diagrams
Practical notes on diagrams, docs, and developer ergonomics — published weekly.
Beautify Mermaid Diagrams in Obsidian and VS Code (Without Leaving Your Editor)
You write Mermaid in Obsidian or VS Code, but the default pastel preview keeps undermining the note you're polishing. Two plugins put a themed renderer in the same pane — no round-trip to a web tool.
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.
Embed Mermaid in Notion: The 4 Working Approaches in 2026
Notion's native Mermaid block is fine for quick notes — but breaks the moment you want a theme, live updates, or a clean export. Here are the four embedding paths that actually work 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.