Publishing Pipeline - inline Mermaid code

Source: Dev.to

What is Mermaid and Why It’s Gaining Traction

Mermaid is a JavaScript‑based diagramming and charting tool that lets you create diagrams entirely from text using a simple, Markdown‑friendly syntax. A tiny block of text like the one below becomes a clean, professional‑looking flowchart when rendered:

graph TD
    A[Start] --> B{Is it working?}
    B -- Yes --> C[Great!]
    B -- No --> D[Fix it]
    D --> B

Diagram Types Supported Out of the Box

• Flowcharts (graph)
• Sequence diagrams
• Class diagrams
• State diagrams
• Entity‑Relationship diagrams
• Gantt charts
• Pie charts
• Requirement diagrams
• Git graphs
• …and more

Comparison to Traditional Diagramming Tools

Why Publishing Mermaid Directly Is Still a Problem

Many popular blogging platforms do not render Mermaid natively:

• WordPress – plugins are inconsistent or outdated
• Medium – no Mermaid support
• Dev.to – partial support only
• Hashnode – works but can be finicky with themes
• Company wikis (Confluence, older platforms) – usually no native rendering

Pasting a Mermaid code block into such platforms results in plain text that is useless to readers.

The Elegant Solution: Render Mermaid to PNG During the Publishing Pipeline

1. Detect Mermaid code blocks – look for fenced blocks that start with mermaid.

       ```mermaid
       graph TD
           A --> B
       ```

2. Generate a unique hash based on the exact diagram content. Identical diagrams are rendered only once, saving storage and processing time.

3. Render the Mermaid code to a high‑quality PNG using a headless browser, the Mermaid CLI, or a Node.js renderer.

4. Upload the PNG to the blog’s media library (e.g., WordPress) or an S3 bucket.

5. Replace the original code block with standard Markdown image syntax.

   ![Diagram alt text](https://example.com/path/to/diagram.png)

6. Fallback behavior – if rendering fails, keep the original code block and log an error. This guarantees that the post never shows a broken diagram.

Benefits

• Works on every platform, even those with zero Mermaid support.
• No broken diagrams – readers always see a crisp image.
• Still version‑controlled – the source Mermaid lives in your repo.
• Deduplication – identical diagrams reuse the same image file.
• High resolution – PNGs look sharp on retina displays.
• SEO‑friendly – images can have proper alt text.

Use Cases & Recommended Tools

Conclusion

Mermaid isn’t trying to replace heavyweight GUI tools like Visio or Lucidchart; it solves a different problem: keeping diagrams in sync with code, version‑controlled, and easy to maintain forever. By rendering Mermaid diagrams to PNGs during the publishing process, you get:

• The maintainability and reproducibility of text‑based diagrams
• The universal compatibility of plain images

The pipeline described above is now live for all upcoming series (e.g., the Puppet HA setup with Foreman, compile masters, and PuppetDB). No matter where readers view the blog, the diagrams will render beautifully.

Happy diagramming! 🚀