Mermaid: Generation of diagrams like flowcharts or sequence diagrams from text

Original Article ↗ Hacker News Discussion ↗

Landscape of text-to-diagram tools

  • A curated list of ~70 browser-based text-to-diagram tools is shared; readers find it surprisingly comprehensive and valuable.
  • Many specialized tools (e.g., for sequence diagrams, database diagrams, genealogical trees) are viewed as better for their niche than generic tools like Mermaid.
  • Alternatives frequently mentioned:
    • Sequence diagrams: WebSequenceDiagrams, js-sequence-diagrams.
    • DB diagrams: DrawDB, dbdiagram.io, Cacoo, sqliteviz, Graphviz-based tools.
    • General drawing/whiteboarding: Excalidraw, Miro.
    • Other text-based diagrammers: PlantUML, Graphviz/dot, D2, Kroki as a wrapper for many syntaxes.

Mermaid’s main strengths

  • Native/inline support in GitHub, GitLab, Notion, Obsidian, Hugo, Jira, Azure DevOps, etc., makes it a de facto choice for diagrams in Markdown and internal docs.
  • Diagrams-as-code fit naturally into repos: editable, diffable, and compatible with git blame and review workflows.
  • Works offline via CLI and editor plugins (JetBrains, VS Code) despite being browser-focused.
  • A near-WYSIWYG editor (mermaidchart.com) eases layout while preserving text-source.

Critiques and limitations

  • Perceived as less powerful and less polished than PlantUML, Graphviz, or specialized tools; syntax is seen as strict and somewhat immature.
  • Local rendering can be awkward (e.g., headless Chrome flows, CLI SVG text issues).
  • Layout struggles with large or complex graphs (schemas with many tables, microservices, etc.), a problem shared with Graphviz.
  • In Notion and some ecosystems, shipped Mermaid versions are outdated.

LLMs and Mermaid

  • Many report strong synergy: LLMs can generate or refine Mermaid from:
    • High-level text descriptions.
    • Codebases or logs.
    • Hand-drawn diagrams (via multimodal models).
  • Some say certain models don’t handle Mermaid well and prefer LaTeX TikZ; others report newer models (including open ones) handle Mermaid reliably.

Use cases and philosophy of diagrams

  • Common uses: system architectures, sequence diagrams, build pipelines, database schemas, story/character relationships, internal engineering docs.
  • Some participants see diagrams as high-value for shared understanding; others argue most diagrams are “write-only,” produced mainly to satisfy process requirements and rarely consulted later.
  • There is skepticism about heavy diagramming cultures (e.g., legacy UML tooling), contrasted with appreciation for lightweight, quickly generated diagrams—especially when LLMs cut creation time to minutes.