Mermaid

Mermaid (also Mermaid.js; source files commonly carry the .mmd extension) is a text-based diagramming language and its reference JavaScript renderer. It was created in 2014 by Swedish software architect Knut Sveidqvist and is developed as an open-source project under the MIT license, with Tyler Long among the long-standing collaborators. A diagram is written as a compact, Markdown-flavored plain-text description, and the library parses that text and lays it out automatically, so the same source that lives in a document also produces the rendered picture.

Every Mermaid document opens with a diagram-type declaration (for example flowchart, sequenceDiagram, classDiagram, stateDiagram, or erDiagram) that selects a grammar; more than twenty-eight types now exist, including Gantt, pie, mindmap, timeline, Sankey, C4, gitGraph, quadrant, and newer additions such as architecture and treemap. For the graph-shaped flowchart type, a direction keyword (TD/TB, LR, BT, RL) sets layout orientation, nodes are declared by id with an optional label and shape (A[Box], B(Round), C{Diamond}), and edges are drawn with arrow operators such as -->, ---, -.->, ==>, plus circle (--o) and cross (--x ) endpoints. Nodes can be grouped into subgraph blocks. Optional YAML frontmatter, inline %%{ }%% directives, and the JavaScript initialize() API supply configuration and theming.

In the graph-data and format-conversion landscape Mermaid occupies the same niche as text-source diagram languages like DOT, PlantUML, D2, and Structurizr DSL: a human-authored syntax whose primary output is a rendered picture rather than a rich interchange model. Layout is computed by the renderer, historically via Dagre-D3 with an optional ELK backend, and drawn with D3 to SVG. Its reach is broad because GitHub, GitLab, Azure DevOps, Notion, and Obsidian render Mermaid code fences natively, and the browser-based Mermaid Live Editor gives an instant preview.

Its strengths are readability, diff-friendly version control, and zero-friction embedding in Markdown. The trade-offs are real: Mermaid targets presentation, not data exchange, so it carries no formal typed graph model, styling and node/edge attributes are limited compared with GraphML or GEXF, automatic layout can crowd or tangle large or dense graphs, and certain reserved words and symbols (notably end) must be quoted to avoid parse errors. Bidirectional conversion tools exist in both directions, including mermaid2dot and dot2mermaid for interchange with Graphviz.