ハクソク

世界を動かす技術を、日本語で。

MermaidダイアグラムをSVGまたはASCIIアートとしてレンダリングする

117日前原文(github.com)

概要

beautiful-mermaid は、AIコーディング支援やCLI環境での図表表示を強化するために開発された テキストベース図表レンダラー。 SVGとASCII/Unicode両対応で、 美しいテーマ と超高速レンダリングが特徴。 2色だけで完結するMonoモード や、VS Codeテーマとの連携も可能。 15種のテーマ を内蔵し、カスタムテーマも簡単作成。 TypeScript製で 依存性が少なく、どこでも動作。

beautiful-mermaid 概要

  • AIアシスタント やCLIツールで図表を即座に可視化できるソリューション
  • Mermaid 標準レンダラーの課題（見た目、カスタマイズ性、依存性、ターミナル非対応）を解決
  • Craft Agents での図表生成のためにCraftが独自開発
  • SVG （リッチUI向け）と ASCII/Unicode （ターミナル向け）の両対応
  • mermaid-ascii （Alexander Grooff氏）のGo実装をTypeScriptへ移植・拡張

主な特徴

  • 5種類の図表 ：フローチャート、状態遷移図、シーケンス図、クラス図、ER図
  • デュアル出力 ：SVG（UI向け）、ASCII/Unicode（CLI/ターミナル向け）
  • 15種類の内蔵テーマ ：すぐ使える美麗テーマ群
  • Shiki連携 ：VS Codeコミュニティテーマをそのまま利用可能
  • ライブテーマ切替 ：CSSカスタムプロパティで即時反映
  • Monoモード ：2色だけで統一感ある美しい図表
  • ゼロDOM依存 ：純粋なTypeScript実装、どんな環境でも動作
  • 超高速描画 ：100件以上の図表を500ms未満でレンダリング

インストール方法

  • npm/bun/pnpm で簡単インストール
    • npm install beautiful-mermaid
    • bun add beautiful-mermaid
    • pnpm add beautiful-mermaid

クイックスタート

  • SVG出力例 
    import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`)
  • ASCII出力例 
    import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)

テーマとカスタマイズ

  • 2色指定だけで美しいMonoモード
    • 例：{ bg: '#1a1b26', fg: '#a9b1d6' }
    • すべての要素色はこの2色から自動派生
  • Enrichedモード
    • 必要な要素のみ色を追加指定可能（例：accent、line、mutedなど）
  • ライブ切替
    • <svg>のCSSカスタムプロパティで即時テーマ変更
  • 内蔵テーマ一覧
    • zinc-light, zinc-dark, tokyo-night, catppuccin-mocha, nord, dracula, github-light, solarized-dark, one-dark など全15種
  • カスタムテーマ作成
    • { bg: '#0f0f0f', fg: '#e0e0e0' }のように簡単指定
    • enrich色追加も柔軟

VS Codeテーマとの連携（Shiki）

  • Shiki のテーマをそのまま図表に反映
    • fromShikiTheme()でVS Codeテーマ色を自動マッピング
    • 例：editor.background→bg、editor.foreground→fgなど

対応図表タイプ

  • フローチャート
    • 方向指定も柔軟（TD, LR, BT, RL）
  • 状態遷移図
    • stateDiagram-v2形式
  • シーケンス図
    • 登場人物間のやり取りを可視化
  • クラス図
    • 継承・属性・メソッド表現
  • ER図
    • エンティティ間のリレーション可視化

ASCII出力詳細

  • Unicode/ASCII両対応
    • Unicode：美しいボックス描画
    • ASCII：最大互換性
  • 出力調整オプション
    • useAscii, paddingX, paddingY, boxBorderPaddingで柔軟制御

APIリファレンス

  • renderMermaid(text, options?): Promise<string>
    • Mermaid記法→SVG変換
    • オプションで色やフォント、透過指定など
  • renderMermaidAscii(text, options?): string
    • Mermaid記法→ASCII/Unicode変換（同期処理）
  • fromShikiTheme(theme): DiagramColors
    • Shikiテーマから図表用カラー抽出
  • THEMES/DEFAULTS
    • 内蔵テーマ・デフォルトカラー参照用

ライセンス・帰属

  • MITライセンス
  • mermaid-ascii （Alexander Grooff氏）の実装を拡張
    • シーケンス図、クラス図、ER図、Unicode対応など多数拡張
  • Craftチーム による開発

beautiful-mermaid は、AI支援開発やCLIツールの図表可視化を革新する 新世代テキストベース図表レンダラー。 「どこでも美しく、誰でも簡単に」図表を扱いたい開発者に最適な選択肢。

Hackerたちの意見

ASCIIダイアグラム大好き！ターミナルでcatコマンドを使っても、ウェブサイトに表示しても同じくらい素晴らしい図が書けるなんてすごいよね。いいモノスペースフォントを使えば、めっちゃシャープに見えるし！このツール、絶対試してみるつもり。あと、一般的なASCIIダイアグラムを作るのに便利なアプリ「monodraw」もおすすめだよ。https://monodraw.helftone.com/

└

^Unicode。

└

重要なのは、ソースコード内でもレンダリングされること。ファイルの最初に良い図があると嬉しいよね。

ライブデモにはAIエージェントプラットフォームのダウンロードが必要なの？試してみたいけど、それが必要ならちょっと躊躇しちゃうな。

└

開発者はクライアント専用のGitHub Pagesを作って、アクセスしやすいデモを用意すべきだよ。プロジェクトをざっと見た感じ、彼らのプラットフォームに縛られずに実現できそうだし。

わお！これ、すごい！サブグラフの方向をオーバーライドできるんだって：外側のグラフがTDの時に、サブグラフ内でLRを使える。これがあれば、スイムレーンダイアグラムに近いものが作れるね。Mermaidにはない機能だし。前にチェックした時、Mermaidは全体のグラフとは違う方向のサブグラフをレンダリングできなかったから。

実際のMermaid ASCIIレンダラーは別のプロジェクトから来てるんだって。[0] このプロジェクトはそれをTypeScriptに移植して、自分たちのテーマを追加したみたい。 [0]: https://github.com/AlexanderGrooff/mermaid-ascii

└

クレジットありがとう！

Obsidian.mdが好きだけど、あまり技術的でない人にはおすすめできないなら、この開発者たちのCraftノートスペースがいい代替になるよ。https://www.craft.do/ 個人にはすごく良いけど、特にチームや、2レベルのグループ化ができるチームのために、すぐに使える強みがある。彼らはCraft Agentsやこのレンダラーに見られるように、全体の製品に同じ...クラフト（あ、言っちゃった）...を持ち込んでいて、元々はMarkdownの哲学から始まった強固な基盤があるよ。創業者のストーリーは、AboutページでLLMフリーな背景を知るのにいいよ。

マーメイドが注目を浴びている間に、Krokiは以下のものを提供してるよ：BlockDiag、BPMN、Bytefield、SeqDiag、ActDiag、NwDiag、PacketDiag、RackDiag、C4 with PlantUML、D2、DBML、Ditaa、Erd、Excalidraw、GraphViz、Nomnoml、Pikchr、PlantUML、Structurizr、Svgbob、Symbolator、TikZ、Vega、Vega-Lite、WaveDrom、WireViz、そしてマーメイド。私のMarkdownエディタ、KeenWriteはKrokiをサービスとして統合してるんだ。つまり、Krokiが新しいテキストベースのダイアグラムフォーマットを提供するたびに、それがKeenWriteで動的に利用できるってこと。チュートリアルもあるよ。 （ちなみに、ダイアグラム内の変数も可能で、最後に示されてるよ。）マーメイドのダイアグラムは、ブラウザ依存のため、ほとんどのライブラリではレンダリングできないから注意してね。

すごくいいね！CCの機能リクエストにぴったりだ。前にオープンしたやつ。

ASCIIダイアグラムに押し進められている理由がよくわからないな（AIの使用に影響されてるのかも）。マーメイドとPlantUMLはすでにテキストベースの表現だし、ほとんどのユーザーが実際に求めているのは、人間向けの標準的で広く認識された表記法でレンダリングされたダイアグラムなんだよね。ASCIIダイアグラムは印刷可能な文字に制約されているから、標準化が難しく、適切なダイアグラムレンダラーと比べて表現力が限られちゃう。

└

ASCIIダイアグラムをコードコメントに入れることができるよ。ターミナルのClaudeコードでも表示できるし。

└

レンダラーが必要ないから、ソースコードのコメントやMarkdownドキュメントに埋め込むことができるんだ。例えば、Gitlabがドキュメントを正しくレンダリングする必要もないし。それに、Markdownドキュメントを編集しているときにも「レンダリング」されるんだよね。

└

文脈が大事だと思う。たまに、mermaidをサポートしてないテキスト形式でドキュメントを書いてることがあって（例えば、リードミーとか、CLIツールに入れる印刷物とかね）、図が必要になるんだ。そういう場合、HTMLとしてレンダリングされたmermaidは選択肢にならないから、これは人間が読みやすい形としてはかなり良い選択肢に思えるよ。

これって、DOMやブラウザエンジンが全く必要ないってこと？それは確かにすごいね。

誰がrehypeプラグインを作るのかな？