Diagram-as-Code: Mermaid and Its Ecosystem

In 2014, Swedish developer Knut Sveidqvist faced a disaster: his carefully crafted Visio flowchart file was corrupted and wouldn’t open. In desperation, watching his daughter enjoy Disney’s The Little Mermaid, he had an epiphany: what if diagrams could be described in text, managed like code?

That chance idea birthed Mermaid—a tool that describes diagrams in text and auto-generates SVG. Today it boasts 85,000 GitHub stars, natively supported by GitHub, and secured a $7.5M seed round.

The Diagram-as-Code Paradigm

“Diagram-as-Code” is simple: use declarative text to describe diagram structure, let layout engines calculate positions, and output vector graphics.

This paradigm brings three revolutionary advantages:

1. Version-controllable: Diagrams stored as text can be committed to Git like code, tracking complete change history
2. Diffable: Text allows precise comparison between versions, unlike graphical files where differences require visual inspection
3. AI-generatable: LLMs understand text better than pixels, making it possible to directly generate diagram code

flowchart TD
  A[Text Description] --> B[Layout Engine]
  B --> C[SVG Output]
  A --> D[Version Control]
  A --> E[AI Generation]
  C --> F[Embed in Docs]
  D --> F
  E --> A

Three Decades of Evolution

The diagram-as-code concept dates back to 1991 at AT&T Bell Labs.

Graphviz: The Grandfather

In 1991, AT&T Bell Labs developed Graphviz, defining the DOT language and providing six layout engines:

• dot: Hierarchical layout for directed graphs
• neato: Spring-model based layout
• fdp: Force-directed layout
• sfdp: Scalable force-directed for large graphs
• circo: Circular layout
• twopi: Radial layout

Graphviz remains the first choice for academic research in complex network visualization—the “grandfather” of diagram-as-code.

PlantUML: The UML Specialist

Launched in 2009, PlantUML focuses on UML diagrams. Implemented in Java, it still uses Graphviz’s layout engine underneath. PlantUML’s strength lies in complete UML standard support—from class diagrams to sequence diagrams, use case diagrams, everything.

Mermaid: The Young Disruptor

Mermaid’s difference lies in not depending on any external layout engine. Instead, it implements its own lightweight layout algorithm based on the dagre library. This allows Mermaid to run directly in browsers without Java environments or backend rendering services.

More importantly, Mermaid supports 15+ diagram types—from flowcharts, sequence diagrams, class diagrams, to Gantt charts, ER diagrams, mind maps—covering almost all technical documentation needs.

In 2022, GitHub announced native Mermaid support—a watershed moment for diagram-as-code. Developers no longer need extra configuration to render diagrams in READMEs, Issues, and Wikis.

D2: The Modern DSL

D2 is a newcomer, using the TALA layout engine instead of dagre, performing better in architecture diagram scenarios. D2’s feature is first-class C4 architecture model support, making system architecture diagrams exceptionally simple to create.

Ecosystem Comparison

Each tool has its strengths; choose based on your scenario:

Beyond these “text-only” tools, some graphical tools deserve mention:

• Excalidraw: Hand-drawn style whiteboard, supports collaboration, perfect for brainstorming
• Draw.io (diagrams.net): Professional diagramming tool with precise controls, ideal for formal documentation

These graphical tools can also export to Mermaid or Graphviz formats, bridging to the diagram-as-code ecosystem.

The Future Is Here

From the despair of losing a Visio file to 85,000 GitHub stars, Mermaid’s decade proves a truth: great technical paradigms often stem from solving a real, specific problem.

Diagram-as-code makes “drawing with text” no longer a fantasy. When AI can understand text and generate code, diagram-as-code becomes the best bridge for AI-generated visualizations—models don’t need to learn complex graphics APIs, just describe diagram structure in natural language, and the layout engine handles the rest.

In the next decade, perhaps we’ll no longer manually draw diagrams, but simply say: “Draw a microservices architecture showing the complete flow from user request to database.”

Diagram-as-code makes this sentence a reality.