Mermaid and Markdown

Every documentation system eventually faces the same problem: diagrams. Prose can describe a process, a system, or a relationship, but at some point a visual representation is clearer than any paragraph. The traditional answer was to open a drawing tool, create an image, export it, embed it, and then update it separately whenever the underlying system changed. The diagram and the text lived in different places and drifted apart at different rates.

Mermaid is an attempt to close that gap. Instead of a drawing tool, you write a short, structured description. Instead of an image file, you get a rendered diagram that lives inline in your Markdown. The source is the diagram, and the source is in the same file as everything else.

How it works — the fenced code block

Markdown has always had fenced code blocks: three backticks, a language identifier, a block of text, three closing backticks. The language identifier tells the renderer what syntax highlighting to apply. Mermaid hijacks this mechanism. Instead of highlighting the source as code, a Mermaid-aware renderer intercepts the block and draws a diagram.

The connection is syntactically trivial. This is a normal Markdown fenced code block that would render as highlighted code in any standard renderer:

```mermaid
flowchart LR
    A[Write documentation] --> B{Has a diagram?}
    B -- Yes --> C[Write Mermaid source]
    B -- No  --> D[Plain prose is fine]
    C --> E[Commit everything together]
```

flowchart LR
    A[Write documentation] --> B{Has a diagram?}
    B -- Yes --> C[Write Mermaid source]
    B -- No  --> D[Plain prose is fine]
    C --> E[Commit everything together]

A renderer that understands Mermaid sees the mermaid language tag and hands the content to the Mermaid library instead of a syntax highlighter. The result is a rendered flowchart, embedded inline where the code block was. A renderer that does not understand Mermaid falls back gracefully: it shows the source as a plain code block. The document remains readable either way.

This is an important design property. Mermaid diagrams degrade gracefully. They are not binary — rendered or broken. The fallback is the source itself, which is structured enough to be understood without rendering.

The shared philosophy with Markdown

Markdown's founding principle, as Gruber stated it in 2004, was that the source should be readable as-is — without a renderer, without special tools, just as plain text. The formatted output should be a convenience, not a requirement for understanding the content.

Mermaid applies exactly the same principle to diagrams. A Mermaid flowchart written in plain text is legible. You can read A --> B --> C and understand that there is a sequence of three steps. You can read A --> B & C and understand a branch. The source is not beautiful, but it is not opaque either.

Both formats also share the same version control property. A Markdown document is a text file. A Mermaid diagram embedded in a Markdown document is still a text file. Both can be stored in git, diffed line by line, reviewed in a pull request, and rolled back to any previous state. An image file embedded in a repository has none of these properties — you cannot diff a PNG. You can diff a Mermaid block.

And then there is a third property that neither Gruber in 2004 nor Sveidqvist in 2014 could have anticipated: text-based formats are natively legible to AI. A Mermaid diagram in a Markdown file is as readable to a language model as it is to a developer. The structural clarity that makes the source human-readable also makes it machine-parseable. The format that was designed for version control and readable diffs turns out to be — by the same logic, not by addition — the diagram format of the AI era.

There is also a maintenance argument. Diagrams created in drawing tools live outside the repository. When the system they describe changes, updating the diagram requires opening a separate application, making changes, re-exporting, and re-embedding. The friction is small but consistent — and consistent small friction is how documentation goes stale. A Mermaid diagram edited in the same file as the code it describes has a much shorter path from "system changed" to "diagram updated".

Diagram types

Mermaid started with flowcharts and sequence diagrams. Over a decade of active development — and significantly accelerated investment after Mermaid joined the Linux Foundation in 2023 — it now covers a wide range of diagram types. Each has its own keyword that starts the block.

The syntax varies significantly between diagram types, but the structural principle is consistent: a top-level keyword declares the type, and the lines that follow describe the content in a format specific to that type. Most syntax can be learned in under an hour for any individual diagram type — or described to an AI assistant and generated correctly without learning the syntax at all.

A sequence diagram example

Sequence diagrams are one of the most useful types in practice — they make API interactions, authentication flows, and system integrations immediately readable.

```mermaid
sequenceDiagram
    autonumber
    participant Client
    participant API
    participant DB

    Client->>API: POST /login (email, password)
    API->>DB: SELECT user WHERE email = ?
    DB-->>API: user record
    API-->>Client: 200 OK (access_token)
    Client->>API: GET /profile (Bearer token)
    API-->>Client: 200 OK (profile data)
```

sequenceDiagram
    autonumber
    participant Client
    participant API
    participant DB

    Client->>API: POST /login (email, password)
    API->>DB: SELECT user WHERE email = ?
    DB-->>API: user record
    API-->>Client: 200 OK (access_token)
    Client->>API: GET /profile (Bearer token)
    API-->>Client: 200 OK (profile data)

The source is legible without rendering. It reads almost like a numbered list of steps. The ->> arrow represents a solid line (request); -->> represents a dashed line (response). autonumber adds step numbers. A developer reviewing this in a pull request can understand the flow from the source alone — the rendered version is a convenience, not a requirement.

Where Mermaid renders

Mermaid's adoption has accelerated in recent years. GitHub's 2022 announcement that it would render Mermaid diagrams natively in Markdown files — README files, issues, pull requests, wiki pages — was a significant inflection point. At that moment, any repository could gain rendered diagrams with no configuration, no build step, and no external service.

The pattern is consistent across platforms: the renderer sees a fenced code block with the mermaid language tag, hands the content to the Mermaid JavaScript library, and replaces the block with an SVG. The format is portable because the convention is simple and the library is open-source.

AI and Mermaid — a natural fit

Every major AI assistant — ChatGPT, Claude, Copilot, Gemini — understands Mermaid natively. Not through a plugin, not through a special mode. They were trained on enormous volumes of open-source Markdown, and that Markdown contained Mermaid diagrams. The result is that Mermaid syntax is as natural to these models as prose.

This matters in both directions. Generation is the obvious case: describe a system or process in plain English and the model returns correct Mermaid source. Comprehension is equally useful: paste a Mermaid diagram into a conversation and ask what it represents, whether it's complete, or where the bottleneck is. Ask it to add a step, rename a participant, or restructure the flow — it can do all of this because the format is text and text is what models are good at.

The practical workflow is fast and stays close to the code. Describe a system, get Mermaid back, paste it into the Markdown file next to the code it documents, commit both together. When the system changes, ask the AI to update the diagram from a description of what changed. The diagram stays in the repository, in the same file as everything else, reviewed in the same pull request as the code change it describes.

An image file embedded in a repository cannot be handed to an AI for modification. A Mermaid block can. That asymmetry is not small. It means diagrams can stay current with far less friction than any drawing-tool workflow allows. The format that was designed to make diagrams version-control-friendly turns out, for exactly the same reason, to be AI-friendly. Same property. Same source.

For new users, this also removes the main adoption barrier. You do not need to learn the syntax before your first diagram. Describe what you want, take what the AI returns, read the source to understand it, and correct from there. The Mermaid live editor at mermaid.live makes it easy to preview and iterate before committing.

A short history

Mermaid was created by Knut Sveidqvist, a Swedish developer, and released as an open-source project in 2014. The initial motivation was straightforward: Sveidqvist was writing documentation and wanted diagrams without leaving his text editor. The existing options — Graphviz, PlantUML, draw.io — all required either a separate installation, a separate workflow, or both.

The project grew slowly at first. GitHub stars accumulated but the user base was largely developers already committed to documentation-as-code workflows. The format was useful but not yet ubiquitous.

Three things changed that. First, GitHub announced native rendering in 2022 — instantly making Mermaid available to every repository on the platform without any setup. Second, AI assistants — GitHub Copilot, ChatGPT, Claude, and others — turned out to understand Mermaid natively. Because the syntax is text-based and present in enormous volumes of open-source Markdown, models can generate, read, and modify Mermaid diagrams from plain-language descriptions. This created a new path to adoption: describe a process, get Mermaid back, paste it into a Markdown file — no syntax knowledge required to produce the first diagram. Third, Mermaid joined the Linux Foundation in 2023, which brought governance, funding, and sustained development at a higher rate than a single maintainer could support.

As of 2024 the project has over 70,000 GitHub stars and is one of the most widely used JavaScript libraries in developer tooling worldwide. Sveidqvist remains involved; the project is now maintained by a team of contributors.

The limits of text-based diagrams

Mermaid is not a replacement for a drawing tool. The constraints are real and worth understanding before committing to it for a project.

Layout is not controllable

Mermaid generates layout automatically. For flowcharts, you can specify direction — top-to-bottom, left-to-right — but you cannot position individual nodes. If the automatic layout produces a visually confusing result, your options are limited: restructure the source, change the direction, or accept the output. This is a fundamental trade-off of the text-based approach. The layout algorithm tries to produce a sensible result; it does not always succeed on complex graphs. One practical response: describe the problem to an AI assistant and ask it to rework the graph structure. It cannot override the layout engine, but it can often restructure the source in a way that produces a more useful automatic result.

Styling is constrained

Mermaid supports themes and some per-node styling via style directives, but it is not a design tool. You cannot control exact colours, fonts, or node shapes beyond what the library provides. For documentation this is usually fine — consistency and legibility matter more than brand fidelity. For presentation diagrams or customer-facing material, a drawing tool will produce better results.

Very large diagrams become unmanageable

A flowchart with fifty nodes is possible to write in Mermaid, but the source becomes hard to read and the rendered output is often dense enough to be useless. Mermaid works well for the kind of diagram that fits on a screen. For complex system architectures with many components, a dedicated architecture modelling tool is more appropriate.

Not all renderers support all types

Support for newer diagram types — mindmaps, C4 diagrams, timelines — varies across platforms. GitHub and the live editor stay current. Other integrations may lag by several library versions. If portability across many platforms is important, stick to the core types: flowchart, sequence, class, ER, and Gantt.

Why it matters for documentation

The argument for Mermaid is ultimately the same argument that made Markdown successful: format should not be the obstacle between the writer and the reader. A developer who wants to document an API flow should not have to open a drawing application, arrange boxes, export a PNG, and embed it. They should be able to write the flow in the same file as the code comment, commit it together, and move on.

Mermaid makes this possible for diagrams in the same way Markdown made it possible for formatted prose. The integration is not incidental — it was designed this way. The fenced code block mechanism that Mermaid uses was already in Markdown. The tooling that renders Markdown already existed. Mermaid extended a pattern that was already proven.

The AI dimension reinforces all of this. Because Mermaid is structured plain text, AI assistants understand it natively — generating diagrams from descriptions, explaining what a diagram depicts, and updating it when the underlying system changes. The same property that makes Mermaid good for version control makes it good for AI collaboration. The diagram stays editable, reviewable, and describable throughout its lifetime.

None of this eliminates the cases where a drawing tool is the right answer. Highly visual presentations, customer-facing material, and complex multi-layer architecture diagrams all benefit from the control that dedicated tools provide. Mermaid fills a specific gap: documentation-grade diagrams, living in code, versioned with the system they describe.

Further reading: mermaid.js.org — official documentation · Mermaid Live Editor · GitHub: Mermaid rendering announcement · Wikipedia — Mermaid (software)

Further reading: Syntax highlighting in Markdown · Jupyter notebooks and Markdown — AI-native by design · Spec-driven development — this is where Markdown really shines