Mermaid’s community dominance and technical shifts

Mermaid holds 90,875 GitHub stars, which is 10.1 times the 9,003 stars held by Draw.io. This popularity is supported by 9,405 forks. The 11.0.0 release fixes undefined values in the defaultConfig that conflict with JSON Schema. These values include class.nodeSpacing and class.rankSpacing, which are integers with a minimum of 0. The project intends to change useWidth from undefined to false to improve stability. While Draw.io grew 7.5% in star count over the last 30 days, Mermaid grew by 0.5%. Mermaid uses TypeScript and Vue, whereas Draw.io uses Java and Bash. Mermaid has 12 years of development history, which is 2 years more than Draw.io. Mermaid supports Entity Relationship, Gitgraph, and C4C diagrams. The MIT license is more permissive than the Apache-2.0 license used by Draw.io.

Automation gaps and UI-first constraints

I see a conflict between WYSIWYG tools and diagram-as-code. General-purpose drawing tools create chaos because users use different versions of UML. In one environment, rectangles are states, while in another they are decisions. Arrows are sometimes labeled for state transitions and sometimes they are unlabeled. In some cases, arrows are labeled state transitions, but other times they are unlabeled and state transitions are also boxes. One developer tried nine different integration strategies to automate Draw.io using headless browsers, including optimistic handshakes and stealth browser contexts, but anti-bot protections and race conditions in the embed API caused every attempt to fail. This person instead built a Mermaid renderer to enable deterministic SVG rendering and programmatic path analysis. This tool, Mermaid2GIF, uses Playwright for headless rendering and FFmpeg to create looping GIFs. Draw.io handles Mermaid code by turning it into editable shapes with Revision History. This allows teams to restyle or rearrange elements. However, Draw.io diagrams are unwieldy when they scale or when a user forgets to edit inter-process connections. Some users prefer Excalidraw because it has a sketch-like character, though it lacks Git compatibility. Some users also use D2, though they miss the GitHub automatic rendering and Sequence diagram numbers that Mermaid provides.

Workflow integration and spec-first tools

Integration capabilities dictate how teams adopt these tools. Swimm uses Mermaid to keep diagrams current with code through Smart Tokens. These tokens allow users to type a backtick within diagram labels to code-couple constants or variables, so renaming a value does not break the documentation. Swimm uses Mermaid for architecture overviews, logical code paths, and user journey charts. Kubernetes uses Mermaid for its documentation, and GitLab uses version 8.8.4 to render charts in its blog posts. In that version, actor in sequence diagrams causes errors, so users must use participant instead. Sequence diagrams in version 8.8.4 also do not work with autonumber, so users must add step numbers directly to the names. The GitLab plugin renders on the client-side, which causes a brief flicker when the page loads and the chart appears in plain text before the JS renders it. In Obsidian, users add a CSS snippet to their folder to prevent Mermaid charts from trailing off the margins. For those who prefer text, a simple ordered list of steps can replace a complex diagram. A developer also created Viewdown, a Markdown viewer, to provide support for Mermaid diagrams, math formulas, and code in 80+ languages. You already know the basics of version control, so I will focus on the tooling. Will the move toward spec-first formats eventually eliminate the need for manual UI drawing?