Diagrams and charts in markdown with Mermaid 🧜♀️
After maintaining scattered draw.io files across multiple repositories for years, I finally moved all our system diagrams to Mermaid. Here's how I did it, focusing on the technical setup and practical benefits that made this transition worth the effort.
The Setup
I use Cursor IDE, but Mermaid works in both Cursor and VS Code. It integrates seamlessly with our existing markdown documentation, providing real-time preview and syntax highlighting. What used to require switching between multiple applications now lives directly in our markdown files.
Github readme files already render mermaid charts since 2012.
In Cursor, just install the Mermaid Preview extension from the marketplace and you're ready to go.
My diagrams now live right in the documentation, using standard markdown code blocks:
graph TD
API[API Gateway] --> Auth[Auth Service]
Auth --> DB[(Database)]
Auth --> Cache[(Redis)]
API --> Search[Search Service]
Search --> ES[(Elasticsearch)]
Why It Works Better
If you're already comfortable with code, you'll find Mermaid's approach surprisingly natural. The text-based format brings several significant advantages over traditional diagramming tools.
Version Control Friendly
Since Mermaid diagrams are just text, they work naturally with git. You can track changes, review differences, and maintain history just like with any other code.
Consistent Formatting
No more fighting with different versions of drawing tools or dealing with inconsistent export formats. The text-based nature keeps everything clean and predictable.
AI-Friendly Updates
The text-based format makes it trivial to use AI for diagram updates. Since it's just text, LLMs can help modify and generate diagrams without specialized tools. Here's a real example of our event-driven architecture:
graph TD
Client --> API[API Gateway]
API --> OrderSvc[Order Service]
API --> PaymentSvc[Payment Service]
OrderSvc --> |publishes| Queue[(Message Queue)]
Queue --> |subscribes| PaymentSvc
Queue --> |subscribes| ShippingSvc[Shipping Service]
subgraph Storage
OrderDB[(Order DB)]
PaymentDB[(Payment DB)]
end
OrderSvc --> OrderDB
PaymentSvc --> PaymentDB
Working with Mermaid
The beauty of Mermaid lies in its simplicity. You don't need to run local servers or deal with specialized APIs. The diagrams render directly in your IDE and on GitHub, and when needed, you can export them to SVG or PNG formats for external documentation.
Impact on Documentation
Moving to Mermaid has transformed how we handle system documentation. Our diagrams now live alongside the code they document, making updates a natural part of the development workflow. The text-based format ensures consistent styling across the team and integrates perfectly with our version control system.
The initial learning curve is minimal - about an hour for developers already familiar with markdown. The long-term impact on our documentation quality and maintainability has made this one of our most significant workflow improvements.