# Mermaid

93 Hacker News commenters recommended Mermaid and 46 criticized it, November 2025 to November 2026. It was recommended in 12 of 13 months. It meets the Hacker Approved badge rule.

**Verdict:** A free text-based diagram tool whose diagrams can be versioned in git and render in GitHub, Markdown and editors, though large diagrams often look messy.

## Why people recommend it

- Diagrams stored as text in git (4 comments): "I love mermaid because I'm a huge fan of anything related to code that can I check into git" ([source](https://news.ycombinator.com/item?id=47577950)) "I am a huge fan of mermaid diagrams because it lets me check in my diagrams into git." ([source](https://news.ycombinator.com/item?id=47572985)) "Mermaid is useful because it's text that can be checked in and versioned as usual." ([source](https://news.ycombinator.com/item?id=47238744))
- Renders in Markdown, GitHub and IDEs (4 comments): "Mermaid diagrams automatically render on Markdown and IDE chat windows as in VSCode or Cursor. So you get the best of both worlds" ([source](https://news.ycombinator.com/item?id=47009653)) "It also renders on GitHub in markdown files with ```mermaid``` code blocks so it's super useful for adding architecture diagrams" ([source](https://news.ycombinator.com/item?id=48830555)) "Mermaid is awesome, since it has broad support, can be committed to repos, and can be created and edited very easily by LLMs." ([source](https://news.ycombinator.com/item?id=47582962))
- LLMs can generate and edit diagrams (4 comments): "An LLM driving mermaid with text tokens will produce infinitely more accurate diagrams than something operating in raster space." ([source](https://news.ycombinator.com/item?id=47058900)) "The LLMs are also pretty good at generating Mermaid charts and tracing execution flows, which is a great way to understand code." ([source](https://news.ycombinator.com/item?id=50090728)) "I've been having great success with LLMs generating Mermaid diagrams and flowcharts from a repo." ([source](https://news.ycombinator.com/item?id=46609144))
- Easy to change and share (3 comments): "I make heavy use of Mermaid as I find it easier to make small changes" ([source](https://news.ycombinator.com/item?id=47575194)) "Mermaid diagrams are even better because you don't waste characters on the visual representation but rather the relationships between them." ([source](https://news.ycombinator.com/item?id=47005638)) "A similar win I've found is documentating process flows with mermaid diagrams (.mmd)." ([source](https://news.ycombinator.com/item?id=47432537))

## What people warn about

- Large diagrams look messy (3 comments): "yes, mermaid is fine; but often looks bad - esp when visualizing large diagrams" ([source](https://news.ycombinator.com/item?id=49862178)) "A lot of diagrams end up looking a bit rough, especially with arrow routing and layout" ([source](https://news.ycombinator.com/item?id=47783909)) "Virtually every diagram it makes that's over 6 nodes becomes a spaghetti mess" ([source](https://news.ycombinator.com/item?id=50097303))
- Heavy browser needed for rendering (2 comments): "It still boggles my mind that mermaid's devs think you need an entire freakin' browser to render an SVG." ([source](https://news.ycombinator.com/item?id=50140265)) "it is very heavy for this purpose (needs an entire chromium instance for the rendering)" ([source](https://news.ycombinator.com/item?id=50141905))
- Layout control is hard (3 comments): "hand-tuning the layout of Mermaid, having to try alternative engines or parameters, is not what I want" ([source](https://news.ycombinator.com/item?id=49269380)) "Mermaid couldn't render subgraphs in a different direction than the overall graph." ([source](https://news.ycombinator.com/item?id=46805551)) "I had to do a lot of hacking/abuse of Mermaid to get it to do what I wanted" ([source](https://news.ycombinator.com/item?id=49644332))

## Alternatives hackers recommend

- [Reladraw](https://hackerapproved.com/p/reladraw.md): 28 recommend
- [SQL to ER diagram tool](https://hackerapproved.com/p/free-sql-to-er-diagram-tool.md): 27 recommend
- [D2 diagram language](https://hackerapproved.com/p/d2.md): 21 recommend
- [PlantUML](https://hackerapproved.com/p/plantuml.md): 16 recommend
- [Graphviz](https://hackerapproved.com/p/graphviz.md): 13 recommend

## Cite as

Hacker Approved, "Mermaid", https://hackerapproved.com/p/mermaid/ (counts from 1,795,640 Hacker News comments, November 2025 to November 2026).