Stop drawing diagrams. Start writing them.
A Swedish architect lost a Microsoft Visio file in 2014 and decided the fix was not a better diagram editor — it was to stop drawing diagrams entirely and write them as text instead. That decision became Mermaid, and it quietly became the default way the modern web draws.
Mermaid is a JavaScript library that turns markdown-like text into diagrams. You write a few lines describing nodes and edges, and it renders a flowchart, sequence diagram, Gantt chart, class diagram, entity-relationship diagram, pie chart, mind map, or state diagram as an SVG. The source is plain text, so it diffs in git, reviews in pull requests, and renders in GitHub, GitLab, Notion, Obsidian, and a dozen other tools natively.
The failure mode Mermaid kills is doc-rot. A diagram you draw in Visio or draw.io is a binary blob: it cannot be diffed, it drifts from the code it describes, and it dies with the person who owns the file. A Mermaid diagram is text, so it lives in the same repository as the code, gets reviewed in the same pull request, and updates in the same commit. When the architecture changes, the diagram changes with it — or the review catches it. That is the whole bet: diagrams as code, not as artifacts.
Mermaid is installed in this environment at version 11.17.1. It renders in the browser from a single script tag, or server-side to SVG for static sites. The kmail.at site pre-renders Mermaid diagrams to SVG at build time (the diagrams on this page are generated that way) so they load fast and match the site theme. You can also run it in CI to fail a build when a diagram is malformed, or use the live editor at mermaid.live to sketch before you commit.
flowchart LR A[Write text] --> B[Parse] --> C[Render SVG]
A[Write text] --> B[Parse] --> C[Render SVG] # renders a left-to-right flowchart with three nodes # and two arrows — that is the whole syntax
The minimal flowchart. `LR` = left-to-right; `TD` = top-down. `[text]` is a rectangle node, `-->` is an arrow.
flowchart TD
A[Start] --> B{Is it a diagram?}
B -- yes --> C[Write mermaid text]
B -- no --> D[Write prose]
C --> E[Render] --> F[Commit to git] --> G[Ship docs] A[Start] --> B{Is it a diagram?}
B -- yes --> C[Write mermaid text]
B -- no --> D[Write prose]
C --> E[Render] --> F[Commit to git] --> G[Ship docs]
# {} is a decision diamond, -- label --> is a labeled edge
A real decision flow. `{}` makes a diamond, and `-- yes -->` labels the edge. This is the shape of most flowcharts you will ever write.
sequenceDiagram
participant U as User
participant B as Browser
participant M as Mermaid
U->>B: open docs page
B->>M: render("flowchart", src)
M-->>B: SVG string
B-->>U: draw diagram User -> Browser -> Mermaid
open docs page
render("flowchart", src)
SVG string
draw diagram
# sequence diagrams model message passing between actors
Sequence diagrams model who talks to whom, in order. `->>` is a solid arrow, `-->>` a dashed reply. `participant X as Label` renames the actor.
gantt title Project Timeline dateFormat YYYY-MM-DD section Build Frontend :b1, 2026-09-10, 10d Backend :b2, 2026-09-10, 12d section Ship QA :c1, 2026-09-22, 5d Launch :c2, after c1, 2d
gantt title Project Timeline dateFormat YYYY-MM-DD section Build Frontend :b1, 2026-09-10, 10d Backend :b2, 2026-09-10, 12d section Ship QA :c1, 2026-09-22, 5d Launch :c2, after c1, 2d # a Gantt chart from a few lines of text
Gantt charts track tasks over time. `section` groups tasks, `:id, start, duration` defines each bar, and `after c1` chains dependencies.
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
USER {
int id PK
string name
string email
} USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
USER {
int id PK
string name
string email
}
# entity-relationship diagram with cardinality
ER diagrams model data. `||--o{` reads as "one to many", `||--|{` as "one to exactly many". Fields go inside the entity block with `PK`/`FK` markers.
| Flag | Meaning |
|---|---|
flowchart | directed graphs with nodes, edges, subgraphs, and decision diamonds |
sequenceDiagram | message-passing between participants, in time order |
gantt | task bars over a timeline, with sections and dependencies |
classDiagram | classes, inheritance, composition, and relationships |
erDiagram | entities, attributes, and cardinality for data models |
stateDiagram-v2 | state machines with transitions and guards |
pie | pie chart from label : value pairs |
mindmap | hierarchical mind map from indented text |
journey | user-journey diagram with task scores |
gitGraph | git commit/branch/merge history |
timeline | chronological events with sections |
quadrantChart | points plotted in four quadrants |
requirementDiagram | requirements and their relationships |
C4Context | C4 architecture context diagrams |
sankey | flow magnitude between nodes |
Mermaid was created in 2014 by Knut Sveidqvist, a Swedish software architect. The origin story is specific: he lost a Microsoft Visio file and realized the real problem was not a better editor but the whole model of diagrams as binary files. If a diagram were text, it could live in version control, diff cleanly, and stay in sync with the code it describes. He named the project after The Little Mermaid, which his children were watching at the time. The first commit landed in November 2014, and the project has been open-source and MIT-licensed ever since.
The core insight borrows from how code already works: text is the most durable, diffable, reviewable format we have. A Mermaid diagram is a few lines of markdown-like syntax that describes structure — nodes, edges, participants, tasks — and the renderer turns that into SVG. Because the source is text, it participates in the same workflows as code: pull requests, code review, git blame, CI. This is the same bet that made Markdown replace WYSIWYG editors for documentation, applied to diagrams.
Mermaid grew from a solo project into the default diagram format of the modern web. GitHub renders it natively in Markdown, as do GitLab, Notion, Obsidian, and many more. In 2019 it won the JS Open Source Award for "the most exciting use of technology". In 2022 Sveidqvist co-founded Mermaid Chart Inc. to build hosted editing and enterprise features on top of the open-source library. As of September 2026 the mermaid-js/mermaid repository has over 90,000 GitHub stars, and the library is at version 11.17.1.
Every Mermaid diagram runs the same pipeline. The source text goes through a lexer and parser that build an abstract syntax tree of the diagram — nodes, edges, and their attributes. A layout engine then positions those elements: flowcharts use a layered graph layout, sequence diagrams stack participants and messages, Gantt charts map tasks onto a time axis. Finally the positioned elements are serialized to SVG. Because the layout is computed, you describe structure and Mermaid decides the geometry — which is why the same source renders consistently everywhere.
Mermaid is a single JavaScript library that runs in any browser, and it can also run server-side to produce static SVG. That is why GitHub, GitLab, Notion, and Obsidian all support it: they each embed the same renderer. For a static site like kmail.at, pre-rendering to SVG at build time means the diagram is a plain file — fast to load, cacheable, and themeable. The diagrams on this page were generated that way, with the site's dark terminal palette.
Mermaid supports themes and theme variables, so diagrams can match a brand or a site. The dark theme used on kmail.at sets the background to the site's void color, node fills to the panel color, borders to the green accent, and edges to cyan — the same tokens as the rest of the design. You can also style individual nodes inline with `style A fill:#0F1A16,stroke:#4ADE80`, which is how the diagrams on this page highlight different stages.