logo

Merman v0.7.0: Mermaid diagrams, rendered headlessly in Rust

227 points FrankZhuang 21 comments
View on Reddit ↗

Hi r/rust,

I’ve been working on Merman, a headless Rust implementation of Mermaid for parsing, layout, and rendering diagrams without needing to spin up a browser or a JS runtime.

GitHub: https://github.com/Latias94/merman
Playground: https://frankorz.com/merman/

I recently cut v0.7.0, which is the first release I feel comfortable sharing more broadly. Side note: Zed currently uses a patched fork of Merman for Mermaid rendering in the editor, which has been a great stress test.

A quick overview:

  • Targets Mermaid 11.15.0 behavior. The test suite currently runs against 3,600+ Mermaid source fixtures with generated golden/layout/SVG baselines to catch regressions against upstream output.
  • Runs completely headlessly and emits SVG, PNG/JPG, PDF, ASCII, semantic JSON, and layout JSON.
  • Includes merman-rustdoc, a proc-macro crate that renders Mermaid fences in rustdoc comments into inline SVG during cargo doc, without injecting Mermaid JavaScript into the generated docs.
  • Available as a Rust crate and CLI, with WASM/TypeScript and FFI entry points for other host languages. The playground above runs the WASM build.

The goal is not to replace Mermaid.js in the browser. This is mostly for native apps, text editors, CI pipelines, preview tools, and doc generators where embedding a JS engine just to draw a flowchart is heavy and awkward.

I keep Criterion benchmarks for regression tracking, but I’m not pitching this mainly as a “faster Mermaid”. Parity and predictable headless output are the top priorities right now.

It’s still early, and Mermaid’s surface area is surprisingly massive. I’d love feedback from anyone who needs diagram rendering in Rust/native apps. If you have weird Mermaid examples that usually break renderers, please throw them my way.

Full Disclosure regarding AI usage: To be fully transparent, the core implementation was heavily bootstrapped with AI coding tools. Mermaid has a massive surface area, and achieving strict, decimal-point parity across all its diagram types, quirks, and edge cases requires an overwhelming amount of boilerplate parsing and layout logic. Writing all of that entirely by hand would have been an unrealistic time sink.

Instead, I used AI as a force multiplier to handle the brute-force implementation, while I focused my engineering effort on strict verification: building the infrastructure, setting up the 3,600+ parity test fixtures, maintaining the CI/CD pipelines, and writing the regression benchmarks. The codebase works deterministically, but because of this approach, you might spot some non-idiomatic Rust in the source. PRs and architectural feedback are very welcome!