In this inaugural episode of Learning the Dots, Alex and Morgan introduce Mermaid.js, an open-source tool that lets you create diagrams using simple text instead of drag-and-drop editors. The conversation focuses on how diagrams-as-code work, why they matter for modern teams, and how tools like Mermaid fit naturally into documentation, collaboration, and version-controlled workflows.

What Is Mermaid.js?

Mermaid.js is a lightweight, open-source diagramming tool that converts plain text into visual diagrams such as flowcharts, sequence diagrams, and class diagrams. By treating diagrams like code, Mermaid makes documentation easier to maintain, review, and share.

Why Diagrams as Code Matter

The hosts explain how traditional diagramming tools often fall out of sync with reality. Mermaid.js solves this by allowing diagrams to live alongside source code, making updates traceable, reviewable, and consistent with how developers already work.

Where Mermaid.js Is Used

Mermaid.js integrates directly into platforms like GitHub and Azure DevOps, allowing teams to render diagrams directly inside Markdown files, pull requests, and documentation. This lowers friction and improves collaboration across technical and non-technical audiences.

Accessibility and Security

The episode also covers two often-overlooked strengths of Mermaid.js:

• Accessibility: Built-in ARIA attributes help ensure diagrams are usable by assistive technologies.
• Security: Sandboxed rendering reduces risk when displaying user-generated diagram content.

Key Takeaway

Mermaid.js isn’t just a diagramming tool—it’s a documentation mindset shift. By turning visuals into version-controlled text, teams gain clarity, consistency, and confidence that their diagrams reflect how systems actually work.

Recap and Close

This episode shows how Mermaid.js simplifies diagramming, improves collaboration, and makes technical documentation more accessible and maintainable.

We’re here to help at Snarful, so reach out on our website if you have any more questions.