Mermaid
JavaScript tool that renders diagrams and charts from Markdown-like text definitions.
Commenters use it to keep diagrams as code inside Markdown documentation123, partly because it renders natively on GitHub with little setup,4 and often have LLMs or coding agents write it for them.5678 The most common complaint is ugly default rendering and weak layouts91011, with others citing a heavy renderer, CVEs and an unwelcome push to monetize.121314
Why people recommend it
LLM-friendly · 3
Commenters routinely have LLMs and coding agents generate Mermaid diagrams, including from handwritten notes.
“diagrams-as-code ideas like Mermaid, all of which LLMs seem to "get" well”
“convert any diagrams that I might have to mermaidjs style”
Show 1 more
“I've had it create diagrams with both the mermaid syntax and AWSDAC (Diagram-as-Code).”
Markdown docs · 3
Pairs well with Markdown for documentation, blog posts and Confluence pages.
“I love Mermaid and Markdown as a combination for documentation.”
“I use Mermaid sometimes in my blog posts.”
Show 1 more
“we mostly render mermaid in confluence documents with a macro that renders it from the source in the document”
Available everywhere · 2
Simple syntax that renders on GitHub and needs less setup than PlantUML.
“mermaid requires a lot less explanation or help with setup.”
“mermaid is very simple”
Architecture diagrams · 2
Used to explain code architecture and to maintain attack trees during security reviews.
“Mermaid when I want my code architecture to be explained”
“I've been using mermaid to create attack trees”
Caveats and dissent
Ugly rendering · 2
Default output looks poor, and some users fall back to hand-made SVG instead.
“I find Mermaid diagram rendering is quite ugly by default.”
“I've always struggled with the presentation”
Layout engines · 1
One user switched to D2 after ELK was removed from the base package and Dagre layouts fell short.
“after they removed ELK from the base. Dagre just doesn’t work for me.”
Heavy renderer · 1
Server-side rendering to SVG needs a full Chromium instance.
“I used mermaidjs for this but it is very heavy for this purpose”
Security · 1
Commenters point to CVEs and an Obsidian warning about potentially unsafe diagrams.
“has a questionable safety record (see CVEs)”
Monetization · 2
Some dislike the move toward a commercial mermaid.ai offering.
“has a questionable safety record (see CVEs)”
Agent output · 2
Some users struggle to get AI agents to produce good Mermaid diagrams.
“I love mermaid but have struggled to get my agents to be any good at it.”
“I've always struggled with the presentation”
Often compared with
Who recommends it in their own words
Threads where it came up
- Pele – Mermaid diagrams as themeable SVG 2 mentions
- Show HN: Reladraw – A diagram language where you decide where to place things 2 mentions
- Show HN: Line9 - a Mermaid rendering engine with its own layout 2 mentions
- Show HN: Whiteboard (YC W26) – An open-source IDE for thoughtful software design 1 mention
- I accidentally turned LLM memory into program analysis 1 mention
- Show HN: Visimer – open-source visual editor for Mermaid diagrams 1 mention
Data: mermaid.json. Quotes are verbatim; the verdict and theme labels are written by a model from these comments, and every clause links to its sources.
All comments 22
“I used mermaidjs for this but it is very heavy for this purpose”
“has a questionable safety record (see CVEs)”
“mermaid requires a lot less explanation or help with setup.”
“I've always struggled with the presentation”
“some simple custom Mermaid format, which the agent can write as artifact files”
“I've been using mermaid to create attack trees”
“I use Mermaid sometimes in my blog posts.”
“after they removed ELK from the base. Dagre just doesn’t work for me.”
“we mostly render mermaid in confluence documents with a macro that renders it from the source in the document”
“Mermaid when I want my code architecture to be explained”
“convert any diagrams that I might have to mermaidjs style”
“Trying to monetize Mermaid was disgusting”
“I love mermaid but have struggled to get my agents to be any good at it.”
“I use a few such as excalidraw/mermaid etc.”
“diagrams-as-code ideas like Mermaid, all of which LLMs seem to "get" well”
“might be great as a library or a lightweight alternative to Mermaid”
“I find Mermaid diagram rendering is quite ugly by default.”
“using ChatGPT for diagrams made me pay for Mermaid.”
“I've had it create diagrams with both the mermaid syntax and AWSDAC (Diagram-as-Code).”
“I love Streamlit and mermaid”
“I love Mermaid and Markdown as a combination for documentation.”
“mermaid is very simple”