Technical writers are shifting from tools like Visio and Lucidchart to Mermaid, a text-based diagramming tool. Its Markdown-friendly syntax makes diagrams version-control friendly, but many blogging platforms like WordPress and Medium still don't render them natively. This leaves diagrams as plain text, undermining their utility.

The author solved this by building a publishing pipeline that automatically detects Mermaid code blocks and renders them to high-resolution PNGs. The process uses a headless browser, generates a unique hash for deduplication, and replaces the code with an image link. This ensures diagrams display correctly everywhere while keeping the source text in Git.

This approach combines the maintainability of code with universal image compatibility. It’s particularly useful for long-lived documentation, like infrastructure diagrams, where diagrams must stay in sync with code. The pipeline is now active for the author's Puppet series, ensuring future architecture diagrams render beautifully across all platforms.