Mermaid made diagrams-as-code stick: sequence diagrams became text inside Markdown

UML was software's grand attempt to standardize design diagrams: OMG accepted it in 1997 and ISO adopted it in 2005. It collapsed under its own weight — the UML 2.2 documentation ran over 1,000 pages and the standard became tied to heavy CASE tools and burdensome pre-work, so by the 2020s proponents and detractors alike agreed it was essentially dead.

One artifact outlived it: the sequence diagram, a simple map of messages flowing between components. Its survivors could draw it, but tooling made it painful — jessems, a developer at BitHawk, found dragging shapes in Lucidchart slow and brittle, with any future change wrecking the layout.

The move was Mermaid, a JavaScript library where you declare the diagram as plain text: participants, arrows and messages written inside a Markdown code fence, rendered by the Markdown toolchain. The author tried it expecting code-on-code to feel wrong, then found it quick, painless and beautiful; he began embedding sequence diagrams in his user stories' implementation plans, previewing them with hot reload and exporting them as images to paste into HTML fields.

Why it stuck is that the diagram became an ordinary code artifact. It lives beside the story it documents, diffs in code review, updates in a one-line edit instead of a redraw, and renders anywhere Markdown does — GitHub Markdown supports Mermaid out of the box, commenters on the Hacker News thread pointed out. Mermaid's founder framed it as informal simplicity replacing the rigid complexity of Rational Rose-era tools.

Make the diagram a code artifact: type it as text in Markdown and let the renderer draw it

Typing a diagram is faster than dragging one, so the authoring cost drops from a canvas session to a few lines beside the doc.

Text versions and diffs like code, so a diagram update is a one-line edit in review instead of a fragile redraw.

Markdown renderers already exist everywhere, so the diagram displays where the team already reads and comments on docs.

UML died by adding complexity; Mermaid kept only the useful artifact and removed the tooling cost around it.

A standard survives by cutting cost where people already work: the diagram that wins is the one you can type in a doc and diff in review.

The post drew 207 points and 111 comments on Hacker News on 24 July 2023. Commenters noted that GitHub Markdown renders Mermaid out of the box, compared it with PlantUML, d2 and Graphviz, and recommended Markdown ecosystems like Docusaurus that render it with one install command. The author kept the workflow at BitHawk, drafting implementation plans whose sequence diagrams live inside Markdown files, with mermaid-cli exporting them as images when records required HTML.