History of Mermaid.js: Diagrams as Code, From a Lost Visio File to 85K GitHub Stars (2026)

In 2014, a Swedish software architect named Knut Sveidqvist lost a Microsoft Visio file. Instead of recreating the diagram by clicking through menus, he asked a different question: what if diagrams were just text?

That question became Mermaid.js — an open-source library that lets you write diagrams the way you write code. Twelve years later, it has 85,000+ GitHub stars, native support in GitHub, GitLab, Notion, and Obsidian, a $7.5M seed round from Sequoia and Microsoft, and 8 million+ users worldwide.

This is the story of how one lost file sparked a movement.

TL;DR: Mermaid.js turned diagrams into text that lives in version control alongside code — eliminating doc-rot and enabling AI-generated visualizations. From a solo project in 2014 to 85K GitHub stars and $7.5M in funding, it's now the standard for diagrams-as-code. Taskade Genesis uses beautiful-mermaid to render all 6 supported diagram types natively in workspaces and blog posts.

🧩 What Is Mermaid.js?

Mermaid.js is a JavaScript library that renders diagrams and charts from Markdown-inspired text definitions. Instead of dragging boxes in a GUI, you write:

That code block renders as a live flowchart — no Visio, no Figma, no screenshot. The diagram lives in your Markdown file, version-controlled alongside your code.

The name? Inspired by The Little Mermaid, which Sveidqvist's children were watching when he started the project.

📜 The Origin Story: A Lost Visio File (2014)

Knut Sveidqvist spent his career in front-end architecture and platform engineering at companies like Telia and GE Lifesciences in Stockholm. A recurring theme across every role: documentation was always out of date.

The breaking point was losing a Visio file. Binary diagram formats like .vsdx couldn't be diffed, couldn't be version-controlled, and couldn't survive a laptop swap. Every time the architecture changed, someone had to open a GUI tool and manually redraw boxes.

Sveidqvist's insight was simple: if documentation is code, diagrams should be code too.

He built the first version of Mermaid.js in 2014 with just two diagram types — flowcharts and sequence diagrams. The syntax was intentionally Markdown-like, lowercase, and readable:

This wasn't just a new tool — it was a new workflow. Diagrams and code travel together, review together, and deploy together.

🔄 The Docs-as-Code Revolution

Mermaid didn't emerge in a vacuum. It arrived alongside a broader movement called docs-as-code — the philosophy that documentation should use the same tools, workflows, and version control as source code.

The movement gained traction at:

• Google — internal g3doc platform stored documentation alongside code in the monorepo
• Spotify — launched TechDocs in 2019, treating docs like microservices
• Squarespace — migrated from Confluence to docs-in-repo
• Write the Docs community — advocated for docs-as-code as an industry standard

Mermaid became the visual layer of this revolution. When your architecture diagram lives in the same PR as the code change, reviewers can verify that the diagram matches reality. Doc-rot — the slow decay of documentation accuracy — was eliminated for visual docs.

📈 Growth: From Side Project to 85K Stars

The growth trajectory of Mermaid.js mirrors the docs-as-code movement itself:

The inflection point was February 14, 2022 — when GitHub announced native Mermaid rendering. Overnight, every GitHub README, issue, PR, and discussion could contain live diagrams. Two weeks later, GitHub Gists followed.

Key Milestones

🏗️ Anatomy of Every Diagram Type

Mermaid.js now supports 15+ diagram types. The beautiful-mermaid renderer — which we use at Taskade to render diagrams in blog posts — supports 6 of these with enhanced SVG output, 15 built-in themes, and synchronous rendering.

Let's walk through every type supported by beautiful-mermaid, with live rendered examples.

Beyond beautiful-mermaid: The Full Mermaid Diagram Catalog

Core Mermaid.js supports 15+ diagram types — far more than the 6 that beautiful-mermaid renders. The full list includes:

The 6 beautiful-mermaid types cover the vast majority of developer use cases. Gantt charts and pie charts remain available in the core library for project management and reporting contexts. C4 diagram support in Mermaid is experimental — for production C4 architecture docs, Structurizr is more mature.

Now let's walk through each beautiful-mermaid type with live rendered examples.

1. Flowcharts — The Original

Flowcharts were Mermaid's first diagram type and remain its most used. They support 12 node shapes, 6 edge styles, subgraphs, and all four directions (TD, LR, BT, RL).

All 12 node shapes:

Edge styles — solid, dotted, thick, bidirectional:

Nested subgraphs with direction override — a real CI/CD pipeline:

System architecture with subgraphs:

2. Sequence Diagrams — Interactions Over Time

Sequence diagrams were the second type Sveidqvist built. They show how actors and systems exchange messages over time — perfect for API flows, authentication, and microservice orchestration.

OAuth 2.0 flow with actors, activation boxes, and notes:

Microservice orchestration with parallel execution and alt blocks:

Database transaction with critical section:

3. State Diagrams — Finite State Machines

State diagrams model system behavior through discrete states and transitions. Mermaid uses the stateDiagram-v2 syntax with support for composite (nested) states.

Connection lifecycle:

Composite states — order processing pipeline:

4. Class Diagrams — Object-Oriented Design

Class diagrams show inheritance, composition, and relationships between objects. Mermaid supports all 6 UML relationship types.

Design pattern — Observer:

All 6 relationship types:

MVC architecture:

5. Entity-Relationship Diagrams — Data Modeling

ER diagrams arrived in Mermaid v8.5, bringing database schema visualization to the text-as-code paradigm. They support 4 cardinality types, identifying vs. non-identifying relationships, and entity attributes with PK/FK/UK markers.

E-commerce schema:

Blog platform with all relationship types:

6. XY Charts — Data Visualization

XY charts are the newest addition to beautiful-mermaid's supported types. They render bar charts, line charts, and combined overlays with support for horizontal orientation and numeric axes.

Monthly active users — bar + line overlay:

Sprint burndown — planned vs actual:

Revenue comparison — 2024 vs 2025:

🤖 Mermaid in the Age of AI

Mermaid's constrained ABNF grammar gives it a unique advantage in the AI era. Unlike free-form visual tools, Mermaid syntax follows strict rules that LLMs can learn with lower hallucination rates than other diagram languages.

The AI-Mermaid ecosystem in 2026:

• ChatGPT — Mermaid Chart plugin for diagram generation
• MCP Server — dynamic diagram generation from any LLM
• Gemini — powers Mermaid AI for intelligent diagram suggestions
• Taskade Genesis — renders beautiful-mermaid diagrams inside AI-generated apps, blog posts, and workspaces

Why beautiful-mermaid Exists

The core Mermaid.js library is optimized for the browser. But modern use cases — server-side rendering, AI pipelines, terminal output — need something different.

beautiful-mermaid by lukilabs was built for the age of AI:

The 15 built-in themes include: zinc-light, zinc-dark, tokyo-night, tokyo-night-storm, tokyo-night-light, catppuccin-mocha, catppuccin-latte, nord, nord-light, dracula, github-light, github-dark, solarized-light, solarized-dark, and one-dark.

At Taskade, we use catppuccin-mocha with our brand accent #ff2d60 — every mermaid diagram on this blog renders through beautiful-mermaid's synchronous SVG pipeline.

⚔️ Mermaid vs. The Competition

Mermaid didn't invent text-to-diagram. Here's how the landscape looks in 2026:

Mermaid's decisive advantage: platform ubiquity. No other text-to-diagram tool renders natively in GitHub, GitLab, Notion, and Obsidian simultaneously.

The Model-Based Alternative: Structurizr

One tool deserves special mention. Structurizr, created by Simon Brown (inventor of the C4 model), takes a fundamentally different approach: instead of drawing individual diagrams, you build a model of your architecture and generate multiple views from it.

Change a service name once → it updates across all diagrams. Add a new component → it appears in every relevant view. This model-based approach eliminates the consistency problem that plagues Mermaid and PlantUML, where the same component might be named differently in different diagrams.

The tradeoff: Structurizr is C4-only (context, container, component, code levels). Mermaid handles 15+ diagram types. Most teams use both — Structurizr for architecture documentation, Mermaid for everything else.

Same Diagram, Three Syntaxes

To illustrate the syntax differences, here's the same simple authentication flow expressed in three languages:

Mermaid (rendered live):

PlantUML (same diagram, different syntax):

@startuml
actor User
User -> [Auth Service]
[Auth Service] -> database [User DB]
[Auth Service] -> [Token Service]
[Token Service] -> [Protected API]
@enduml

D2 (same diagram, cleanest syntax):

User -> Auth Service -> User DB
Auth Service -> Token Service -> Protected API

Mermaid's syntax sits between PlantUML's verbosity and D2's minimalism. The tradeoff: Mermaid has the broadest rendering support, D2 has the cleanest output, PlantUML has the most diagram types.

Choosing the Right Tool: Practitioner Insights

Jacqui Read, author of Communication Patterns (O'Reilly), teaches a workshop on diagrams-as-code with AI. Her framework for choosing between tools:

1. What diagram type do you need? Activity diagrams → PlantUML. C4 architecture → Structurizr. Flowcharts and sequences → Mermaid.
2. What does your organization already use? If your knowledge management renders Mermaid, stick with Mermaid.
3. Do you need a model or just diagrams? Structurizr maintains a model behind the scenes — change a service name once and it updates across all views. Mermaid and PlantUML are stateless diagrams.
4. Where will diagrams render? Mermaid is JavaScript-native (easy for web platforms). PlantUML requires a Java runtime (harder to integrate).
5. License compatibility — all three are open source but with different licenses.

"You can't just say 'we're only going to use Mermaid in our organization.' It doesn't cover everything you're going to need. In some contexts you'll choose one and in some contexts another." — Jacqui Read

The critical gap Read identifies: Mermaid has no legend/key feature. PlantUML has one (though clunky). Structurizr auto-generates legends from the model. For production architecture docs, this matters.

The Hallucination Problem

When LLMs generate Mermaid diagrams, the results vary based on how specific your prompt is:

• Too high-level ("create a diagram of my system") → hallucinated syntax, made-up keywords
• Too specific ("move elements from left to right") → LLMs invent non-existent arrow modifiers
• Just right ("reorder these elements so X appears on the right") → correct output

Read's observation: the prompt for generating a sequence diagram via LLM is often longer than just writing the Mermaid code directly. The real value of LLMs is in conversion (PlantUML → Mermaid → Structurizr), error debugging, and generating diagrams from existing code — not writing diagrams from scratch.

Spec-Driven Development: Diagrams as Validation

A new movement in 2026, spec-driven development, uses Markdown specifications (part human, part AI) to drive code generation. Diagrams-as-code plays a validation role:

The pattern: give an LLM your architecture spec (with Mermaid diagrams), let it generate code, then ask a different model to diagram the generated code. Compare the two diagrams visually. Humans are good at spotting visual mismatches — better than reading thousands of lines of code.

"The diagrams aren't necessarily for the AI. They're for humans to validate what the AI produced." — Jacqui Read

🌍 Platform Integrations

The breadth of Mermaid integrations in 2026 is unmatched:

The February 2022 GitHub announcement was the inflection point. Before that, developers needed browser extensions or custom build steps. After, any README.md with a mermaid code block rendered automatically. Stars jumped from ~35K to 52K in a single year.

💰 From Open Source to $7.5M: Mermaid Chart Inc.

In 2022, Sveidqvist partnered with Open Core Ventures to co-found Mermaid Chart Inc., with Andrew Firestone as CEO. The thesis: Mermaid's open-source library is the foundation; the company builds commercial collaboration, editing, and enterprise features on top.

In March 2024, Mermaid Chart raised a $7.5M seed round from Sequoia, Microsoft M12, and Open Core Ventures — a strong signal that diagrams-as-code had matured from developer curiosity to enterprise infrastructure.

The business model follows the open core pattern:

📊 The Flowchart Renaissance

Flowcharts were Mermaid's first diagram type — and they remain its most commercially valuable. Keywords like "flowchart generator," "generate flowchart," and "flowchart maker" consistently rank among the highest-converting search terms in the productivity and diagramming space.

Why? Because flowcharts solve a universal problem: making complex processes visible. Business workflows, onboarding sequences, decision trees, approval chains — every organization has processes that live in someone's head until a flowchart externalizes them.

Mermaid AI: Natural Language to Flowchart

Mermaid Chart's AI chat interface takes this further — you describe a process in plain English and get a rendered flowchart instantly:

"Create a user sign-in flow for a website"

The AI generates the flowchart, and you iterate conversationally: "Introduce a forgot password flow", "Make the diagram more visually appealing". Each prompt refines the diagram in real time. The result is a fully customizable flowchart — editable via AI chat, visual editor, or raw Mermaid code — in under two minutes.

This workflow is why AI flowchart generators have exploded — tools like Taskade's Flowchart Maker and Flowchart Creator let anyone build professional process diagrams from a single prompt.

For pre-built starting points, explore flowchart templates or use AI flowchart agents that design, refine, and maintain diagrams that stay synced with your actual workflows.

Claude Code: Architecture Diagrams from Context

Where Mermaid AI handles individual flowcharts, Claude Code with Opus 4.6 generates entire architecture diagrams from codebase context:

• Point Claude at a file → get a flowchart of the code's logic
• Describe a system → get a Mermaid sequence diagram of the data flow
• Ask for a CI/CD pipeline → get a rendered graph with all stages

The key insight: Claude generates both Mermaid (structured, precise, version-controlled) and Excalidraw (hand-drawn, collaborative, presentation-ready) from the same prompt. Mermaid for documentation that lives in Git. Excalidraw for whiteboard sessions with the team.

IDE Integration: Diagrams Where You Code

The Mermaid ecosystem now extends into every major code editor. A single plugin works across VS Code, Cursor, Windsurf, and Google's Project IDX (all VS Code forks sharing the same extension system):

• Live preview — edit Mermaid code on the left, see the rendered diagram update on the right
• AI generation — ask the editor's AI to create a Mermaid diagram from any file in your project
• Cloud sync — connect diagrams to your Mermaid Chart account across editors
• Export — PNG, SVG, or raw Mermaid code from the preview panel

The workflow: write code → ask AI to diagram it → preview renders live → export or commit the .mmd file alongside the code. Diagrams stay version-controlled, reviewable, and always in sync.

For teams looking for alternatives to standalone diagramming tools, Taskade offers a free Whimsical alternative and free Miro alternative with AI-powered flowchart generation built into every workspace.

🔮 The Future: Diagrams Generated, Not Drawn

The trajectory is clear. Diagrams are moving from manually drawn → text-defined → AI-generated.

In the AI-generated phase, you don't write graph TD — you describe what you want:

"Show me how our authentication service handles OAuth flows with the user database and cache layer"

The LLM outputs valid Mermaid syntax. The renderer (like beautiful-mermaid) converts it to SVG. The diagram lives in your docs, updates when the code changes, and renders everywhere your Markdown goes.

This is exactly what Taskade Genesis enables. Build an AI app with a single prompt, and the agents generate architecture diagrams, data flow charts, and process maps — all as Mermaid code blocks that render live in your workspace.

🛠️ Getting Started with Mermaid in 2026

Mermaid Live Editor — The Fastest Way to Start

The quickest path to your first diagram: open mermaid.live in your browser. No installation, no account, no setup. Type Mermaid syntax on the left, see the rendered diagram on the right. Export as PNG, SVG, or shareable link.

The Live Editor is how most developers first encounter Mermaid — and it's the best way to prototype a diagram before committing it to your repo.

In GitHub

Just add a mermaid code block to any Markdown file:

```mermaid
graph LR
    A[Your Idea] --> B[Your Diagram]
```

That's it. No extensions, no build steps, no configuration. Works in README files, issues, PRs, discussions, and Gists. Also supported natively in GitLab (since v10.3) and Azure DevOps.

In Your Editor

The Mermaid VS Code extension provides live preview — edit code on the left, see the diagram update in real time on the right. The same extension works in Cursor, Windsurf, and Google's Project IDX since all are VS Code forks.

Install from the extensions marketplace → create a .mmd file → right-click → "Preview Diagram."

In Taskade

Every Taskade blog post and workspace supports mermaid code blocks rendered via beautiful-mermaid with the catppuccin-mocha theme and teal accent. Taskade Genesis AI agents can generate diagrams from natural language descriptions — just describe the process and get a rendered flowchart or architecture diagram.

With beautiful-mermaid (Code)

import { renderMermaidSVG, THEMES } from 'beautiful-mermaid';

const svg = renderMermaidSVG('graph LR\n  A --> B --> C', {
  theme: THEMES['catppuccin-mocha'],
  accent: '#00d4aa',
  transparent: true,
});

Synchronous. No DOM. Works anywhere JavaScript runs — server-side rendering, CLI tools, CI pipelines, React useMemo().

📐 Mermaid Best Practices

Lessons from teams using Mermaid at scale:

1. Keep diagrams under 30 nodes. Beyond 30, layout algorithms struggle and the diagram becomes unreadable. Split into multiple diagrams with a clear hierarchy (overview → detail).

2. Use subgraphs for grouping. Don't let a flat flowchart sprawl. Subgraphs create visual boundaries that help readers parse the diagram:

3. Label everything. Every edge should have a label. Every node should have a human-readable name, not just an ID. Unlabeled arrows are the #1 source of diagram misinterpretation.

4. Choose direction intentionally. graph TD (top-down) for hierarchies. graph LR (left-right) for sequences and pipelines. Don't default to one direction for everything.

5. Store diagrams alongside code. The whole point of diagrams-as-code is co-location. Put your .mmd files in the same directory as the code they describe. Review them in the same PR.

6. Don't diagram everything. Document the "why" and the high-level "how." The lower you go in detail, the faster diagrams rot. API interfaces and system boundaries — yes. Individual function calls — usually no.

🧬 From Text to Living Diagrams

Knut Sveidqvist lost a Visio file in 2014. Twelve years later, his frustration powers 85,000+ stars of open-source infrastructure, native rendering in every major developer platform, and an AI-ready grammar that LLMs produce more reliably than any other visual language.

The lesson: the best tools don't just solve a problem — they change the workflow. Mermaid didn't make better diagrams. It made diagrams a natural part of how developers think and communicate.

At Taskade, we took this one step further with Taskade Genesis — where AI agents don't just generate diagrams, they generate entire living applications with diagrams embedded. Your workspace becomes the runtime. Your agents become the team. Your automations become the execution.

One prompt. One app. Diagrams that live.

Try Taskade Genesis free →

📚 Further Reading

Flowchart & Diagram Tools

• AI Flowchart Generator — Create professional flowcharts from natural language
• AI Flowchart Maker — Streamline workflows with AI-powered diagrams
• Flowchart Templates — Pre-designed templates for processes, decision trees, and workflows
• AI Flowchart Agents — Agents that design, refine, and maintain process diagrams
• Free Whimsical Alternative — AI-powered diagramming in Taskade
• Free Miro Alternative — Collaborative flowcharts without the premium price

AI & Technology Deep Dives

• What Is Agentic Engineering? — How AI agents are reshaping software development
• How Do Large Language Models Work? — Transformers explained from attention to generation
• What Is Intelligence? — From biological neurons to AI agents
• They Generate Code, We Generate Runtime — The Taskade Genesis manifesto
• Types of Memory in AI Agents — How agents remember and learn
• What Is AI Safety? — The complete guide to risks, alignment, and the future
• What Is Mechanistic Interpretability? — Understanding what happens inside neural networks
• What Is Grokking in AI? — When models suddenly learn
• Agentic Workflows: Path Towards AGI — Design patterns for autonomous AI

Explore Taskade

• Taskade Genesis — Build AI Apps — One prompt, one living app
• AI Agents — Custom agents with tools, memory, and multi-model collaboration
• Automations — Temporal durable execution with 100+ integrations
• Taskade Community — Templates, agents, and workflows

Frequently Asked Questions