Mermaid

The more I look into mermaid.js the more I’m convinced it’s a psyop.

As far as I can tell, pretty much everyone in the open–source community was happy with Graphviz for a long time. It’s widely supported, has tons of implementations—including WASM, Rust, etc.—and just works. Its output can be styled pretty much arbitrarily, converted to and from a plethora of different formats, it can work in the browser or serverside. It’s great.

Suddenly, Mermaid shows up out of nowhere and starts replacing Graphviz at an unexplainable rate. GitHub, Notion, Obsidian, GitLab, Azure Devops—these are just a few of the projects that support Mermaid. I suspect it’s no coincidence that a lot of them are commercial and proprietary. I think any open–source developer without a complete disregard for compatibility or filesizes quickly realizes the problems with Mermaid:

• Mermaid is extremely lacking in facilities to control the layout of its rendered diagrams, and its layout logic is highly unpredictable and entirely undocumented.
• Mermaid has over 1900 dependencies, uses a number of different build systems stitched together, and has virtually no developer documentation.
• The Mermaid repository has a bot that autocloses issues after 30 days. This means countless important bugs and problems go unfixed, since their reports are being held hostage and shot if the authors politely wait for a maintainer to respond.
• Mermaid graphs use nonportable CSS/SVG constructs that cause them to be completely and utterly broken in virtually any context other than a browser, including even Reader Mode.
• A minified distribution of Mermaid is 2.9MB. For comparison, this entire website, at the time of writing this, is 1.6MB. The home page is less than 600kB, of which ~280kB is d3.js (for rendering the link graph at the bottom) with a further ~200kB taken up by fonts.
• Mermaid requires a browser window to work. At first glance, there does exist an official CLI to render graphs outside of a browser context, but… it just uses Puppeteer to download Chrome, spawn a new headless Chrome process, and render a web page with Mermaid on it. This website builds in sub–80ms [Building Foxspace - Foxspace is made possible by spacedock, my Obsidian–vault–to–Zola–site compiler. Since neither Obsidian nor Zola alone fulfill all my needs, I…]; adding a single diagram to be rendered with mermaid-cli increases the build time to 1.5s.
• There is an (unofficial) mermaid-server which can run in the background and render graphs as responses to HTTP requests; it would be logical to assume that it spins up a browser and keeps it open to avoid waiting for the startup every time, but… it just calls mermaid-cli when it receives a request.

As far as I can tell, it is highly nontrivial to make use of Mermaid in a remotely acceptable way. I have spent multiple days trying to find a solution to render Mermaid graphs both without introducing a bazillion of system dependencies to spacedock and in a way that actually produces valid SVG files. I’m convinced that either of these problems is unsolvable without entirely rewriting the majority of Mermaid, much less both of them at the same time.

Ultimately, though, my primary goal with spacedock is to make writing as effortless as possible. Mermaid is built into Obsidian and its syntax is faster to write than GraphViz’s, so ideally I’d still like to render Mermaid graphs on this site; I just find mermaid.js itself to be unacceptable for this (or any) purpose.

The current plan is to implement a Mermaid-to-GraphViz transpiler instead. The output will differ significantly from that of mermaid.js, but for reasons mentioned above I’d consider that a feature.