Tools: Publishing Pipeline - inline Mermaid code

Enhancing Blog Posts with Mermaid Diagrams: Why They’re a Game-Changer (and How to Make Them Work Everywhere) ## What Is Mermaid? ## Example: A simple flowchart ## Why Mermaid Is Winning Hearts in 2025/2026 ## The One Big Challenge: Platform Support ## The Solution: Render Mermaid to PNG in Your Publishing Pipeline ## How it works ## Benefits of this approach ## When to Use Mermaid vs. Traditional Tools ## Final Thoughts ## Related posts In today’s technical blogging world, clear, accurate, and up-to-date diagrams are essential for explaining complex systems—whether it’s architecture, workflows, data flows, or infrastructure layouts like the Puppet setups we’ve been exploring in this series. For years, tools like Microsoft Visio, Lucidchart, draw.io (now diagrams.net), or even PlantUML have been go-to solutions. However, more and more authors (especially in the DevOps, cloud, and open-source communities) are turning to Mermaid — and for good reason. In this post, we’ll explore: Mermaid is a JavaScript-based diagramming and charting tool that lets you create diagrams entirely from text using a simple, Markdown-friendly syntax. graph TD A[Start] --> B{Decision?} B -->|Yes| C[Do Something] B -->|No| D[Do Something Else] C --> E[End] D --> E That tiny block of text becomes a clean, professional-looking flowchart when rendered: Mermaid supports many diagram types out of the box: Here are the key advantages of Mermaid compared to traditional tools like Visio, Lucidchart, or even draw.io: In short: Mermaid turns diagrams into code — which means they become first-class citizens in your documentation repository, just like your README, tests, or configuration files. While GitHub, GitLab, Obsidian, Notion (recently), and many static site generators now render Mermaid natively, many popular blogging platforms still do not: So what happens when you paste a beautiful Mermaid code block into a blog post on one of these platforms? → It just shows up as plain text — completely useless to readers. This is exactly the problem I wanted to solve for my Puppet blog series. Mermaid isn’t trying to replace heavy-duty GUI tools like Visio or Lucidchart — it’s solving a different problem: “How can I keep my diagrams in sync with my code, version-controlled, and easy to maintain forever?” By rendering Mermaid diagrams to PNGs during the publishing process, we get the best of both worlds: This new pipeline is now live for all coming series like the Puppet series — so all future architecture diagrams (like the Puppet HA setup with Foreman, compile masters, and PuppetDB) will render beautifully, no matter where you read the blog. Have you started using Mermaid in your documentation? Or are you still exporting screenshots from draw.io? Let me know in the comments — I’d love to hear your workflow! Happy diagramming! 🚀 Did you find this post helpful? You can support me. Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse - What Mermaid is and why it’s gaining so much traction - How it compares to traditional diagramming tools like Visio and draw.io - The biggest challenge when publishing Mermaid diagrams on blogs - The elegant solution: rendering Mermaid to PNG during the publishing pipeline (exactly what I’ve now implemented!) - Flowcharts (graph) - Sequence diagrams - Class diagrams - State diagrams - Entity-Relationship diagrams - Gantt charts - Requirement diagrams - WordPress (even with plugins) often has inconsistent or outdated Mermaid support - Medium does not support Mermaid at all - Dev.to supports it only partially - Hashnode has good support but can be finicky with themes - Company wikis, Confluence instances, or older platforms → usually no native rendering - Detect Mermaid code blocks The pipeline looks for standard fenced code blocks starting with ``` mermaid 2. Generate a unique hash based on the exact content of the diagram → Identical diagrams are rendered only once (great for performance and storage) 3. Render the Mermaid code to a high-quality PNG Using a headless browser + Mermaid CLI (or a Node.js renderer). In my case, Jenkins runs that as part of the pipeline. 4. Upload the PNG to the blog’s media library (e.g., WordPress media uploads) or an S3 bucket. 5. Replace the original code block with proper Markdown image syntax: . In my case this is done by the python logic of the pipeline at runtime. 6. Fallback behavior If rendering fails for any reason → the original Mermaid code block remains unchanged (and an error is logged) - Works on every platform — even those with zero Mermaid support, since a centrally placed image is loaded - No broken diagrams — readers always see a nice image - Still version-controlled — the source Mermaid code lives in your repo - Deduplication — same diagram across multiple posts reuses the same image file - High resolution — PNGs look crisp on retina displays - SEO-friendly — images have proper alt text (you can customize this further) - The maintainability and reproducibility of text-based diagrams - The universal compatibility of plain old images - Building a Write-Once Publishing Pipeline - Publishing Pipeline v1.1.0 – Dev.to Support and What Comes Next - Publishing Pipeline v1.2.0 – backlinks and X support - Publishing Pipeline - Refactoring