pretty-mermaid

Pretty Mermaid

バンドルされた Node.js CLI を使って Mermaid 図を作成またはレンダリングします。拡大縮小可能なドキュメントには SVG、共有やラスター形式のみを扱うツールには PNG、ターミナルやプレーンテキストには ASCII または Unicode を使用します。

作業ディレクトリ

このファイルを含むディレクトリを <skill-root> として扱います。バンドルされたスクリプトはこのディレクトリから実行するか、絶対パスで呼び出してください。ユーザーのソースとレンダリング出力は、ユーザーが指定した場所に保持し、レンダラーをユーザーのプロジェクトにコピーしないでください。

ワークフロー

1. ユーザーから Mermaid のソースが提供されているか、文章から図を作成する必要があるかを判断します。
2. 以下の表から図の種類と出力形式を選びます。
3. 構文、テーマの選択、または API の動作について詳しい情報が必要な場合に限り、関連するリファレンスファイルを読みます。
4. 新しいソースは .mmd ファイルとして保存し、ユーザーの用語と関係性を維持します。
5. 名前付きのテーマまたは明示的な色を指定してレンダリングします。
6. 結果を確認します。構文エラー、切り抜き、レイアウトの混雑、または不明瞭なラベルがあれば修正して、再度レンダリングします。
7. ソースと出力のパス、および選択した形式とテーマを提示します。

ユーザーから置き換えを依頼された場合を除き、既存のソースファイルや出力ファイルを上書きしないでください。

図の種類を選ぶ

ニーズ	図の種類	ひな形
プロセス、意思決定ツリー、アーキテクチャ	フローチャート	flowchart LR
API 呼び出し、メッセージ、やり取り	シーケンス図	sequenceDiagram
ライフサイクルまたは有限状態機械	状態図	stateDiagram-v2
クラス、モジュール、関係性	クラス図	classDiagram
データベースのエンティティと多重度	ER 図	erDiagram
棒、線、傾向、比較	XY チャート	xychart-beta

複雑な Mermaid 構文を作成する場合は、references/DIAGRAM_TYPES.md を読んでください。

出力を選ぶ

出力	最適な用途	備考
SVG	README、ドキュメント、スライド、Web サイト	拡大縮小可能で、テーマを適用でき、透過に対応しています
PNG	チャット、プレビュー、ラスター形式のみを扱うツール	--format png を指定します。外部コンバーターは不要です
Unicode	最新のターミナルや読みやすいテキストプレビュー	デフォルトの ASCII レンダラー出力
プレーン ASCII	ログや機能が制限されたターミナル	--use-ascii を追加します
ANSI カラー付きテキスト	対話型ターミナル	--color-mode を指定します

基本コマンド

これらのコマンドは <skill-root> から実行します。

テーマを一覧表示する

node scripts/themes.mjs

SVG をレンダリングする

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.svg \
  --theme tokyo-night

ターミナル用テキストをレンダリングする

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.txt \
  --format ascii \
  --color-mode none

Unicode の罫線文字を使用できない場合は、--use-ascii を追加します。

PNG をレンダリングする

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.png \
  --format png \
  --width 1200 \
  --theme tokyo-night

ディレクトリ内の図を一括レンダリングする

node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./rendered \
  --format svg \
  --theme github-dark \
  --workers 4

3 つ以上の図をレンダリングする場合や、ディレクトリ内に一貫したオプションを適用する場合は、一括レンダリングを使用します。

テーマの選択

• 一般的なダークモードのドキュメント：tokyo-night
• GitHub のダークまたはライトの表示面：github-dark、github-light
• 印刷物やプレゼンテーション：zinc-light
• 高コントラストの配色：dracula
• 寒色系で控えめな配色：nord、nord-light

見た目のテーマ選択が重要な場合は、references/THEMES.md を読むか、docs/THEME_GALLERY.md を開いてください。名前付きのテーマは、明示的な色指定で調整できます。

便利なオプション

共通のスタイル設定

オプション	用途
--theme <name>	組み込みの 15 種類のテーマから 1 つを適用します
--bg、--fg	必須の基本色を設定します
--line、--accent、--muted	コネクター、強調表示、補助テキストを調整します
--surface、--border	ノードの塗りつぶしと線を調整します
--font <name>	SVG のフォントファミリーを設定します

SVG

オプション	用途
--transparent	SVG の背景を削除します
--padding <n>	キャンバスの余白を設定します
--node-spacing <n>	ノード間の水平間隔を設定します
--layer-spacing <n>	レイヤー間の垂直間隔を設定します
--component-spacing <n>	接続されていないコンポーネント間の間隔を設定します
--interactive	XY チャートのホバーツールチップを有効にします

PNG

オプション	用途
--width <n>	アスペクト比を維持しながら、出力幅を 100～10000 ピクセルに設定します
--transparent	透明な背景を保持します

ターミナル出力

オプション	用途
--use-ascii	Unicode の罫線を通常の ASCII 文字に置き換えます
--padding-x、--padding-y	図の間隔を調整します
--box-border-padding	ノードボックス内の余白を調整します
--color-mode <mode>	none、auto、ansi16、ansi256、truecolor、または html

正式な CLI オプション一覧は、node scripts/render.mjs --help または node scripts/batch.mjs --help を実行して確認してください。

作成ガイド

• 短く具体的なラベルを優先し、ユーザーが使っているドメイン固有の用語はそのまま使用してください。
• 分岐やメッセージの意味が曖昧な場合は、明示的なエッジラベルを使用してください。
• 大きな図は、文字を小さくするのではなく、関連のない要素を分割して読みやすくしてください。
• 横長のフローには LR、縦長のドキュメントには TB を使用してください。
• 色だけで意味を伝えないでください。
• 印刷にはライトテーマを使用し、最終的な背景に対するコントラストを確認してください。
• 慣れない構文は assets/example_diagrams/ から始め、図のリファレンスを参照してください。

検証

レンダリング後、以下を確認してください。

1. コマンドが正常に終了し、出力ファイルが空でないことを確認します。
2. SVG 出力が <svg で始まること、PNG 出力が有効な画像として開けること、テキスト出力に図の内容が表示されていることを確認します。
3. レイアウトが重要な場合は、特に長いラベル、CJK テキスト、接続されていないコンポーネント、XY チャートについて、視覚的な出力を確認します。
4. 矢印、カーディナリティ、状態、ラベルが元の依頼と一致していることを確認します。
5. サポートされていない構文を黙って削除せず、レンダラーの制限事項を報告してください。

このスキル、そのスクリプト、テンプレート、またはリファレンスを変更する場合は、npm test と npm run validate の両方を実行してください。

トラブルシューティング

• 依存関係が見つからない場合：<skill-root> で npm install を実行してください。CLI も初回実行時にインストールを試みます。
• 不明なテーマの場合：node scripts/themes.mjs を実行し、一覧にある名前を正確に指定してください。
• 構文エラーの場合：references/DIAGRAM_TYPES.md を参照し、エラーが発生する箇所まで縮小してから、図を段階的に復元してください。
• SVG が混み合っている場合：--node-spacing、--layer-spacing、または --component-spacing を大きくしてください。
• PNG の色に関するエラーの場合：カスタムカラーには具体的な16進数の値を使用してください。解決できない外部 CSS 変数はラスタライズできません。
• リダイレクトした出力にターミナルのカラーエスケープコードが含まれる場合：--color-mode none を使用してください。

リファレンスの参照先

リソース	読む、または使用するタイミング
references/DIAGRAM_TYPES.md	Mermaid 構文の作成またはデバッグ
references/THEMES.md	テーマの比較またはカスタムカラーの定義
references/api_reference.md	スクリプトの拡張、または beautiful-mermaid の直接呼び出し
docs/THEME_GALLERY.md	視覚的にテーマを選ぶ
assets/example_diagrams/	サポートされている図のテンプレートを基に作成する
scripts/render.mjs	1つの図をレンダリングする
scripts/batch.mjs	ディレクトリ内の図を並列でレンダリングする
scripts/themes.mjs	インストール済みテーマを一覧表示する