マーメイド：テキストからフローチャートやシーケンス図のような図を生成する

概要

Mermaid は、Markdown風テキストから ダイアグラム を生成するJavaScriptツールです。 ドキュメント作成 と開発の同期を支援し、簡単に図を修正・更新することが可能です。非プログラマーでも Live Editor で視覚的に操作できます。多彩な 統合・連携 があり、GitHubなど様々なアプリで利用可能です。セキュリティ面も考慮し、 サンドボックス 描画など安全対策を実装しています。

Mermaid: Markdown風テキストからダイアグラムを生成するツール

Mermaidの概要

JavaScriptベース で動作するダイアグラム・チャート生成ツール
Markdown風テキスト 記法とレンダラーを利用すること
ドキュメントと開発の 同期遅延（Doc-Rot） 問題を解消すること
図やドキュメントの 作成・更新コスト削減 を実現すること
非プログラマー でもLive Editorで直感的に図を作成・編集できること

主な特徴・用途

Flowchart、Sequence diagram、Gantt chart、Class diagram など多様なダイアグラムをサポートすること
- 例: フローチャート、シーケンス図、ガントチャート、クラス図、状態遷移図、円グラフ、Gitグラフ、バーグラフ、ユーザージャーニー図、C4図
Live Editor でリアルタイム編集・プレビューが可能であること
GitHub や他アプリケーションとの統合が容易であること
生産性向上 や組織内ナレッジ共有を促進すること

利用方法・導入

CDN やnpm経由で簡単に導入できること
Markdown ファイル内でコードブロックとして記述・管理すること
Live Editor やCLI、HTTPサーバーなど多様な利用方法があること
GitHub などのプラットフォームでそのまま利用可能であること

コミュニティ・貢献

オープンソース であり、貢献者を常時募集していること
貢献ガイド やIssueを通じて参加・支援が可能であること
Argos や applitools によるPRのビジュアルリグレッションテストを導入すること
AI Bot によるサポート（コード例、インストールガイド、デバッグ支援など）を提供すること

セキュリティ対策

ユーザー入力による 悪意あるスクリプト 混入リスクを認識・対策すること
サンドボックス化iframe による安全なレンダリング方式を採用すること
一部インタラクティブ機能は制限されるが、 セキュリティ優先 を徹底すること
脆弱性報告 は security@mermaid.live へのメールで受付すること

感謝・謝辞

d3、dagre-d3、js-sequence-diagram など外部プロジェクトへの感謝を表明すること
貢献者 全員への謝意を示すこと
開発者 Knut Sveidqvist による ドキュメントの簡易化 目的での創設を伝えること

参考・ドキュメント

公式ドキュメント やチュートリアル、初心者ガイドを参照すること
Integrations and Usages リストで対応アプリケーションを確認すること
リリース手順 やバージョン管理、npm publish方法を確認すること

Hackerたちの意見

これがトップページに載ってるのを見るのはちょっと変な感じ…mermaidはずっと前からあるし、実際の使い道はあんまり良くないと思う。

└

俺は使ってるし、月に何回も見るよ。gitリポジトリや静的サイトでグラフィックや図をMarkdownに貼るのに一番便利な方法だからね。ドキュメントにシーケンス図を入れて、gitを使って時間の経過とともに変更を追跡するのがめっちゃ便利。これ以外にソフトウェア開発者が何を使ってるのか気になるな。LucidやVisioみたいな特定のグラフや描画ツールも試したけど、mermaidのシンプルさがいいんだよね。それに、誰がいつ図を変更したかをgit blameで表示できるツールは他に知らない。

└

こういうことがあると嬉しいな。みんなほとんどいつも、何かクールな使い方や発見を教えてくれるんだよね。リンク自体は新しくないけど、コメントは結構新しいことが多い。

└

実際の使い方は、ウェブページ上で図を描くことだよ！スクリーンショットとしての図より、コードとしての図の方が断然好きだな。例えば、https://sbs.johnnydecimal.com/14.23+OPS1#diagram

個人的にはmermaidは素晴らしいと思うけど、二つの間接的な理由があるかな：- mermaid用のほぼWYSIWYGエディタが https://www.mermaidchart.com/play にあるんだ。すごく便利で、矢印を描くとレイアウトが適切に変わる！ - Notionはコードブロック内でインラインのmermaidチャートをサポートしてる（プレビュー付き！）エンジニアリングドキュメントにアーキテクチャ図を入れるのに最高だよ。

└

ObsidianもMarkdownコードブロック内でインラインのmermaidチャートをサポートしてるよ。あんまり言われない機能の一つだね。

└

Githubもインラインのmermaidチャートをサポートしてるよ！最近、大きめのPRに入れ始めたけど、レビュアーたちがすごく気に入ってる。

└

Hugoもこれやってるよ。

└

Notionについてだけど、確かにMermaidをサポートしてるけど、含まれてるバージョンがかなり古いし、アップデートする気はあまりなさそう。残念だね。

今までのマルチモーダルLLMの中で一番好きな使い方は、1. 自分が作業しているパイプラインのDAGをペンと紙で描くこと。2. グラフの写真を撮ること、間違いも含めて。3. ChatGPTにその画像をmermaid.jsに変換してもらうこと。自分が扱っているパイプラインがどれだけ複雑で、手描きの画像がどれだけ雑でも、このワークフローがうまく機能するのは本当に驚きだよ。

└

プロンプトを共有してくれない？俺はKindle Scribeで結構描くんだ。これを試してみたいけど、君のプロンプトが役立ちそうだな。

└

代わりに、LLMに今のコードのマーメイドDAGを作成させてみて。

└

最近、描く代わりにシステムが何をするべきかを高レベルで説明するために、いくつかの箇条書きとテキストをざっと書いたバリエーションをやったんだ。それからチャットGPTにユースケースを特定してもらって、各ユースケースのシーケンス図をpuml形式（plantuml）で生成してもらった。驚くほど効果的で、約5分で終わったよ。これは、いくつかのパートナー企業と共有した技術提案で、顧客に詳細な計画を提供するためのものだった。数週間にわたって詳細を交渉するオンライン会議の後に出てきたものだから、かなり重要な文書だったし、好評だったよ。Plantumlは見た目も悪くないから、生成した図をドキュメントに貼り付けても大丈夫。私は忙しい人間だから、書くだけのドキュメントを生成するために何時間も時間を取る余裕はないんだ（誰も読まないし、真剣に価値を感じることもない）。それでも、たまにはあった方がいいこともある。上の例はその良い例だね。人々はざっと見て、ちょっといいねをくれて、計画通りに進めて請求する許可をくれる。仕事は終わり。誰も数秒以上見ないようなリファレンスデザインではないからね。数十年業界にいると、図の価値とそれを作るために必要な時間に対して非常に懐疑的になる。正直、あまり見えないんだ。良いソフトウェアは図なしでもたくさん作られてるし、青写真のための青写真は必要ない（ソースコードは動作するソフトウェアに自動的にコンパイルするための青写真だから）。人々がソースコードの構造、可読性、簡潔さを重視するのには理由がある。それは、ソースコードをデザイン資産として扱えるようにするためだ。私はUMLを書かずに、データクラスやインターフェースをスタブアウトするんだ。そして、それを何度もリファクタリングする。図は私を遅くするだけなんだ。でも、数分なら、図を作るために脳のサイクルを無駄にする閾値に近いかな。すでにテキスト形式で書いているドキュメントを豊かにするために。さっとメモを取るだけ。これらのマイクロ言語の不格好な構文にこだわる時間を全く無駄にせず、要点を押さえよう。もっと良いLLMや大きなコンテキストウィンドウを使えば、1分くらいにまとめられると思う。「このプロジェクトを調べて、すべてのデータベーステーブルの概要図を作成して」。これが私が書くプロンプトだね。同じように、LLMにコードをドキュメント化させるのは時間の使い方として素晴らしいよ。

Mermaidが好きじゃないし、Graphviz/dotみたいなものよりデザインが良くないと思う。一般的に、プログラマーじゃない人が使うには文法が厳しすぎると思うけど、Mermaidの大きな魅力はGitHubでインラインで動くことなんだ。シーケンス図をたくさん作るから、編集可能なmermaidがあるのはすごく便利だよ。ただ、GitHubの巨大なmermaidナビゲーションコントロールが右下に浮いてて、物が隠れちゃうのは残念だな。

└

マーメイドはgraphviz dotのラッパーだと思ってたんだけど。

Excalidraw（https://excalidraw.com/）がコメントに出てないのはちょっと驚きだね。俺は開発者やデザイナーにアイデアを伝えるために定期的に使ってるよ。それに、jsonにエクスポートもできる！誰かがmermaidをexcalidrawに変換するライブラリも作ったみたい。今はexcalidraw/mermaidを使って面接で聞くデザインの質問を作る実験をしてるんだ。

└

ちょっと前にExcalidrawを使ってシステムデザインの面接を受けたんだけど、すごく楽しかったよ（普段から普通の仕事でもよく使ってるから、慣れてたしね）。

└

Excalidraw大好きなんだけど、編集可能で差分も取れるテキスト表現ってあるのかな？あまり手間をかけずに生成できて、自動でレイアウトもできるといいな。

昨年、認証フローを描こうとしたときにこれを使ったのを覚えてる。Excalidrawを使おうとしたんだけど、チャートが大きすぎるとラグが出ちゃうし、マウスを使うよりもチャートをタイプする方が楽だと思った。

ビルドシステムを比較するビデオトークで、ビルドステップのシーケンスから複数のシーケンス図を作成するのにマーメイドを使ったよ - https://www.youtube.com/watch?v=L67ri_xe2oQ（スライド - https://paulhammant.com/google-style-dag-build-systems/）。私にとっての新しいブーストはGPT4oだった。ビルドログだけからすぐに欲しいものを作ってくれたけど、手動で調整する必要もあった。次の新しい（またはとても古い）問題は、十分なセーブポイント（URLブックマーク）を取らずに、URLを失ったせいで同じ編集を二回やっちゃうことだった。それぞれのPNG形式の二回目の保存（https://kroki.io/mermaid/svg/...）が、変更を追跡する問題をさらに増やして、特に疲れている時は大変だったよ :(

└

面白いスライドだね！こういうシステムの設定方法がいろいろ見られるのはいいし、実用的なgitリポジトリもあって素晴らしい！

Krokiをチェックしてみて！いろんなテキスト駆動のダイアグラムジェネレーター（Mermaid、PlantUML、Ditaa、GraphViz、SVGBobなどなど）をまとめて使えるマルチシンタックスラッパーだよ。 https://kroki.io/

本当に欲しいのは、30以上のマイクロサービスとその相互接続を見栄えよく図示できるものなんだ。graphvizはまあまあだけど、同じk8sネームスペース内のサービスを近くにまとめるために、もう少しグルーピングのレベルが欲しいな。

└

クラスターだけじゃ足りないの？ネストできるよ。 https://graphviz.org/Gallery/directed/cluster.html https://github.com/ReneNyffenegger/about-Graphviz/blob/maste...

やっぱりd2の方が好きだな。https://d2lang.com/ 唯一の欠点は、ブラウザ内でレンダリングできないことかな。

└

以前、wasmバージョンを作ってたみたいだね。[0] どれくらい使えるかはわからないけど、興味があるかもしれない。[0]: https://github.com/terrastruct/d2/pull/436/files

ハクソク