merman: Mermaid を CLI・サーバー・ネイティブアプリに埋め込める headless Rust renderer

Mermaid を使う場面はかなり増えています。

README に flowchart を入れる;
設計文書に architecture 図を書く;
CI で static docs を生成する;
内部 platform の preview に図を埋め込む;
PNG や PDF に落としたり、terminal で text 版を見たくなったりする。

ただ、Mermaid を browser や Node toolchain の外へ持ち出そうとすると、急に難しくなります。

必要になるのは単なる「render できるか」ではなく、

headless 環境で安定して動くか;
Rust、C、Python、Flutter のような host に埋め込めるか;
CI や server-side で batch 生成できるか;
上流の Mermaid にできるだけ近い結果を保てるか。

今日書いておきたい Latias94/merman は、まさにそこを狙った project です。自分自身を “Mermaid.js, but headless, in Rust.” と説明していて、browser の外側で使える Mermaid rendering stack を作ろうとしています。

GitHub repository page と README を 2026-06-22 時点で見ると、この repository は 382 stars、14 forks、主要言語は Rust。作成日は 2026-02-10、公開上の最新更新日は 2026-06-22 です。license は MIT / Apache-2.0 の dual license。GitHub Releases page で見える最新の正式 release は 0.7.0 で、日付は 2026-06-09 です。

Project overview

項目	内容
Repository	Latias94/merman
位置づけ	CLI、server-side、native host 向けの headless Mermaid Rust renderer
Stars	382
Forks	14
主要言語	Rust
作成日	2026-02-10
最終更新日	2026-06-22
License	MIT / Apache-2.0
Latest stable release	0.7.0
Release date	2026-06-09

解いているのは「どう描くか」より「browser なしでも崩れずに使えるか」

merman でまず面白いのは、最初から front-end widget として作られていないことです。

README に並んでいる入口はかなりはっきりしています。

merman-cli として使える;
Rust crate として組み込める;
merman-ffi で stable C ABI を提供する;
browser / TypeScript package がある;
Python、Flutter、Android、Apple 側の binding の土台も持つ。

つまりこれは単に Mermaid preview を出す tool ではなく、複数の runtime に配れる rendering capability を作ろうとしている project です。

ここが、単一用途の Mermaid tool と少し違うところです。browser 内だけで完結するなら「図が出る」で十分ですが、merman が相手にしているのはもっと難しい問題です。

DOM がない場所でどう render するか;
異なる host にどう stable な interface を出すか;
SVG 以外に PNG、JPG、PDF、terminal text をどう扱うか;
上流 Mermaid の挙動とどう整合させるか。

出力面が広く、SVG だけで終わらない

merman README で印象的なのは、出力 surface がかなり広いことです。

単に Mermaid source を SVG に変えるだけでなく、次のようなものも返せます。

semantic JSON;
layout JSON;
Mermaid 互換寄りの SVG;
ASCII / Unicode の terminal 図;
SVG を経由した PNG、JPG、PDF。

この中で特に実用的だと思ったのは 2 つあります。

1 つは semantic / layout JSON です。つまり black-box renderer ではなく、parse 結果や layout 結果を中間成果物として他の tool に渡せます。

もう 1 つは ASCII / Unicode output です。これによって doc rendering tool だけでなく、CLI、TUI、log、plain text doc のための diagram engine としても使いやすくなります。

こうした出力面を 1 つの stack としてまとめようとしているのが merman の面白さです。

一番価値があるのは、Mermaid 上流との alignment を本気で扱っていること

「Mermaid っぽいものを一部 render できる」project 自体は珍しくありません。

merman が一段面白いのは、Mermaid を仕様そのものとして扱うと README に明言している点です。上流の挙動が少し不思議でも、Rust らしく勝手に解釈し直すのではなく、できるだけ合わせに行く姿勢が見えます。

そのために用意されている quality gate もかなり重厚です。

fixtures/**/*.golden.json で semantic snapshot を固定;
fixtures/**/*.layout.golden.json で layout を固定;
upstream Mermaid が出した SVG を end-to-end baseline に使う;
見た目だけでなく DOM parity を検証する;
README では 23 diagram family、3500+ upstream SVG baselines と明記している。

このやり方はかなり engineering-oriented です。

diagram renderer は「だいたい似ている」で流しやすいですが、CI、batch export、cross-platform embedding に入ると、その小さな差異が積み重なって問題になります。merman はその差異を最初から regression asset にしているわけです。

FFI と host text measurement callback が、native embedding で効いてくる

local CLI で図を出すだけなら、Mermaid renderer は他にもあります。

でも merman には、より platform 寄りの軸があります。merman-ffi で stable C ABI を出し、Python、Flutter、Android、Apple/Swift などへ binding を広げる前提で作られています。

ここが大事なのは、Mermaid の埋め込みで本当に難しいのが parser そのものより、

text measurement;
font fallback;
native host 独自の layout system;
SVG や <foreignObject> への platform ごとの対応差。

といった部分だからです。

README では、host が自前の text measurement callback を提供できるようにしていて、無理な場合は vendored の compatibility measurer に fall back する構成を説明しています。この分離はかなり実務的です。

headless renderer が完全な geometry を一方的に決められるわけではなく、最終的な見え方は host の font 環境にも影響されます。merman はその現実を無視せず、最初から interface と fallback を設計しています。

単なる library ではなく、workflow に入る documentation tooling になりつつある

README 全体を見ると、merman はもう単一 crate だけの project ではありません。

repository には複数の作業面が分かれています。

merman-cli は detect / parse / layout / render workflow を担当;
merman-rustdoc は rustdoc 内の Mermaid fence を扱う;
@mermanjs/web は browser package;
merman-typst-plugin は Typst 系 host の可能性を探っている。

つまり、これは単一 API というより source から doc、export、embedding までをつなぐ道具立て に近づいています。

技術文書や developer platform を触る人にとっては、この方向はかなり魅力があります。なぜなら本来は自分で組み合わせなければならないものが多いからです。

Mermaid parser;
SVG renderer;
PNG exporter;
多言語 binding;
quality gate と regression fixture。

そこを 1 つの project がある程度まとめてくれるなら、長く使える基盤になりやすいです。

互換性を重視するからこそ、限界も正直に書いている

もう 1 つ良いと思ったのは、README が「何でも完璧にできる」とは書いていないことです。

公開文書では、いくつかの現実的な限界も明示されています。

SVG の <foreignObject> は一部 rasterizer と相性が悪い;
text measurement は host の font 環境に影響される;
PNG / JPG export には default の pixmap budget がある;
一部の複雑な layout は geometry-normalized な形で upstream と合わせている。

この種の注意書きはむしろ信頼感があります。

diagram rendering stack では、engineering で潰せる問題と、interface や budget や fallback で制御するしかない問題が分かれています。そこを曖昧にせず説明している project は、実運用に持ち込みやすいです。

なぜ今追っておきたいのか

merman が面白いのは、Mermaid そのものが新しいからではなく、Mermaid を browser 以外でも正式な workflow に入れたいという需要に真正面から応えているからです。

この需要は、いくつかの文脈で同時に増えています。

static doc generation;
server-side の batch rendering;
desktop / mobile の native embedding;
CLI / TUI での text diagram 表示;
upstream behavior に敏感な automated testing。

Markdown にたまに図を置くだけなら、公式 CLI でも十分かもしれません。でも Rust service、native app、cross-language plugin、CI の docs pipeline で Mermaid を継続的に使うなら、merman のような headless + embeddable + alignment-heavy な方向はかなり魅力的です。

まとめ

Latias94/merman の価値は、Rust で Mermaid renderer を作ったこと自体よりも、Mermaid を CLI、server-side、native host、documentation pipeline に入る基礎能力 として扱っていることにあります。

SVG だけでなく、semantic/layout JSON、ASCII/Unicode output、PNG/JPG/PDF export、FFI まで含めて surface を広げ、そのうえで upstream Mermaid との alignment に大きなコストを払っている。そこがこの project のいちばん面白い点です。

front-end 用のおもちゃではなく、engineering workflow に耐える headless Mermaid stack を探しているなら、merman はかなり追う価値があります。