Mermaidを超えて: Vega-LiteとMarkdownでリッチなチャートを作成する

ドキュメントにおいてチャートが重要な理由

ドキュメントの読者にデータを説明する際、百聞は一見に如かずと言えます。チャートを活用することで、読者は傾向を特定し、分布を理解し、パターンを一目で把握できるようになります。2026年6月30日現在、より多くのチームがドキュメントやナレッジベースを自動化する中で、Markdownに直接リッチなビジュアル表示を埋め込む機能が不可欠になりつつあります。

課題となるのは、多くのチャートツールがシンプルさか強力さのどちらか一方を重視して設計されており、両方を兼ね備えていることが滅多にない点です。生成が容易で、プロフェッショナルな見た目を持ち、ドキュメント作成のワークフローに自然に収まるツールが求められます。

Mermaidが得意なこと（そしてその限界）

Mermaidはその役割において非常に優れています。フローチャート、シーケンス図、Ganttチャート、円グラフ、基本的な棒グラフなどに対応しています。チャートのニーズがシンプルであれば、Mermaidが最適な選択肢です。広くサポートされており、記述が容易で、ほとんどのMarkdown環境でレンダリングできます。

しかし、Mermaidは統計的ビジュアル表示のために設計されたものではありません。2つの変数間の関係を示す散布図の作成を試みたり、カテゴリごとの強度を示すヒートマップ、分布を比較する箱ひげ図を試みたりしてみてください。Mermaidでは対応できないか、不十分にしか対応できません。Mermaidに組み込まれているチャートタイプのセットを超える機能が必要になった場合、行き詰まってしまいます。

テクニカルドキュメントにおいてデータビジュアル表示がますます一般的になっているため、この制限は重要です。APIのレスポンスタイム、機能の採用率、あるいはユーザーのエンゲージメントパターンを示す場合でも、Mermaidが提供できる機能ではすぐに物足りなくなるでしょう。

Vega-Liteの紹介: より強力なアプローチ

Vega-Liteは、インタラクティブなビジュアル表示を作成するための宣言型文法です。チャートを手作業で描画する代わりに、JSONを使用して記述します。データを指定し、列を視覚的プロパティ（x軸、y軸、色、サイズ）にマッピングすると、Vega-Liteがビジュアル表示をレンダリングしてくれます。

このアプローチにはいくつかの利点があります。第一に、柔軟であることです。Vega-Liteは棒グラフ、折れ線グラフ、散布図、ヒートマップ、箱ひげ図、エリアチャート、その他多数のタイプをサポートしています。第二に、データ駆動型であることです。データセットを提供し、データを視覚的にエンコードする方法を指定します。第三に、Markdownとの親和性が高いことです。Vega-Liteの仕様をドキュメントに直接埋め込むことができます。

Vega-Lite JSON仕様の理解

Vega-Liteの仕様は、チャートを記述するJSONオブジェクトです。以下は散布図を作成するシンプルな例です。

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "title": "Product Sales vs Marketing Spend",
  "data": {
    "values": [
      {"spend": 1000, "sales": 5000},
      {"spend": 2000, "sales": 8000},
      {"spend": 3000, "sales": 12000}
    ]
  },
  "mark": "point",
  "encoding": {
    "x": {"field": "spend", "type": "quantitative"},
    "y": {"field": "sales", "type": "quantitative"}
  }
}

この仕様の内容は次のとおりです。提供されたデータを取得し、各行をポイントとしてプロットし、 spend 値をx軸に配置し、 sales 値をy軸に配置します。レンダリングはVega-Liteが処理します。

これをさらに複雑にすることも可能です。色やサイズ、複数のレイヤー、フィルタリング、インタラクティブ機能を追加できます。しかし、このようなシンプルな仕様であっても、Mermaidでは扱えないユースケースに対応できます。

MarkdownへのVega-Liteの埋め込み

MarkdownにVega-Liteチャートを埋め込むには、通常、特別なレンダラーを備えたコードブロックを使用します。一部のMarkdown環境では、 vega-lite を言語識別子としてサポートしています。

{"$schema": "https://vega.github.io/schema/vega-lite/v5.json", "data": {"values": [{"x": 1, "y": 2}, {"x": 2, "y": 4}]}, "mark": "line", "encoding": {"x": {"field": "x"}, "y": {"field": "y"}}}

他のプラットフォームでは、Vega-Lite仕様をレンダリングするサービスを使用する必要があります。ドキュメントツールの中にはVega-Liteをネイティブにサポートしているものもあれば、プラグインやラッパーを必要とするものもあります。

静的画像に対する利点として、これらのチャートはインタラクティブである点が挙げられます。読者はホバーして正確な値を確認したり、詳細をズームインしたり、データ系列の表示/非表示を切り替えたりすることができます。

AIおよび自動化との統合

Vega-LiteがAI主導のドキュメント作成に適している理由の1つは、JSON形式が言語モデルにとって生成しやすいからです。AIエージェントに「このデータを表すチャートを作成して」と依頼すると、曖昧さなく有効なVega-Lite仕様を出力できます。

これにより、新しいワークフローが可能になります。生のデータを取得して適切なビジュアル表示を自動生成し、それをMarkdownに埋め込むドキュメント生成スキルを想像してみてください。あるいは、新しいデータセットを受け取り、オンデマンドでチャートを再生成するドキュメントパイプラインも考えられます。

AIエージェントはデータに適したチャートタイプを選択することもできます。言語モデルはデータセットを確認し、「これは分布のように見えるので、ヒストグラムを使用しよう」「これは時系列データなので、折れ線グラフを使用しよう」と判断できます。これにより、どのチャートを使用するかを判断する手動の手順が不要になります。

チャート生成ワークフローの構築

ステップ1: データの準備

構造化された形式でデータを収集します。JSON配列が適していますが、CSVやその他の形式でも問題ありません。各レコードに明確なフィールド名があることを確認してください。

[
  {"month": "January", "revenue": 45000, "expenses": 32000},
  {"month": "February", "revenue": 52000, "expenses": 35000},
  {"month": "March", "revenue": 58000, "expenses": 38000}
]

ステップ2: ビジュアル表示の設計

データが何を物語っているかを考えます。傾向を示していますか？比較ですか？分布ですか？これによってチャートタイプが決まります。

ステップ3: Vega-Lite仕様の生成

JSON仕様を記述するか、AIツールを使用して生成します。データソース、チャートタイプ、および列を視覚的プロパティにマッピングする方法を指定します。

ステップ4: Markdownへの埋め込み

Markdownドキュメント内のコードブロックに仕様を挿入します。正しくレンダリングされることを確認してください。

ステップ5: チャートのドキュメント化

チャートが何を示しており、なぜそれが重要なのかについて短い説明を記述します。文脈を与えることで、ビジュアル表示が情報へと変わります。

一般的なチャートタイプと使用すべきタイミング

散布図は2つの連続変数間の関係を示すのに適しています。ヒートマップは2つの次元にわたる強度の表示に優れています。箱ひげ図はグループ間の分布を比較します。折れ線グラフは経時的な変化を追跡します。棒グラフはカテゴリ間の値を比較します。最適な選択は、データと答えようとしている疑問によって異なります。

制限事項とトレードオフ

Vega-Liteは強力ですが、あらゆるユースケースにおいて完璧というわけではありません。非常に大規模なデータセット（数百万行）はレンダリングを低速化させる可能性があります。一部の特殊なチャートタイプはVega-Liteの適用範囲外です。また、複雑なビジュアル表示ではVega-Lite仕様が冗長になることがあります。

また、すべてのMarkdownビューアがVega-Liteをサポートしているわけではありません。GitHubのMarkdownレンダラーはネイティブでサポートしていませんが、GitHub-Flavored Markdownウィキや一部のドキュメントプラットフォームはサポートしています。読者がVega-Lite未対応のプラットフォームでドキュメントを読む場合、チャートはレンダリングされません。

結論

Vega-Liteは、ドキュメントツールチェーンにおける重要なギャップを埋める存在です。統計的ビジュアル表示を扱い、Markdownと統合し、AI主導の自動化と上手く連携し、インタラクティブなチャートを生成します。Mermaidでは物足りなくなった場合、Vega-Liteは自然な次のステップとなります。

メリット

• Mermaidが提供する以上の多数のチャートタイプをサポート
• 宣言型JSON形式はわかりやすく、AIとの親和性が高い
• ホバーツールチップやズームなどのインタラクティブ機能により視認性が向上
• 外部画像ファイルなしでMarkdownにすっきりと埋め込める
• 無料かつオープンソース
• バックエンドのレンダリングを必要とせずブラウザ上で動作

デメリット

• すべてのMarkdownレンダラー（特にGitHub）でネイティブにサポートされているわけではない
• 複雑なチャートの場合、Mermaidよりも学習曲線が急である
• 大規模なデータセットはレンダリング性能に影響を与える可能性がある
• 他の宣言型チャート言語と比較してJSON仕様が冗長である
• レンダリングにはプラットフォームのサポートが必要であり、サポートがない場合は未レンダリングのコードブロックにフォールバックする

注意事項

本記事に記載されているデータ、フィールド名、およびサンプル値は、説明用のプレースホルダーです。本番環境のドキュメントでVega-Liteを使用する前に、読者が閲覧するプラットフォームでチャートをテストしてください。一部の環境では、Vega-Liteをレンダリングするために追加の設定やプラグインが必要です。ズームやフィルタリングなどのインタラクティブ機能が期待どおりに機能することを必ず確認してください。自己責任で進行し、特定のドキュメントプラットフォームや読者に合わせてアプローチを調整してください。

よくある質問

• 既存のMermaidチャートをVega-Liteに変換するにはどうすればよいですか？
• Vega-Liteはリアルタイムデータやストリーミングデータを扱うことができますか？
• 1つのページに多数のVega-Liteチャートを埋め込んだ場合、パフォーマンスにどのような影響がありますか？
• ドキュメントのテーマに合わせてVega-Liteチャートのスタイルを設定するにはどうすればよいですか？
• Vega-LiteとVegaは同じものですか？また、どのような違いがありますか？
• Vega-LiteでPDF用の印刷可能なチャートを生成できますか？
• モバイルデバイスでVega-Liteチャートをレスポンシブに対応させるにはどうすればよいですか？
• グループを比較するのに最も適したVega-Liteのチャートタイプは何ですか？

タグ

#dataviz #vega-lite #markdown #documentation #charts #visualization #json #webdev #tutorial #analytics