BlumeとmicroCMSと組み合わせて人とAIに届くドキュメントサイトを作ってみた

ドキュメントサイトを作るとき今ままでは「読みやすいページをどう用意するか」が中心でした。ところが今は、検索、Markdownでのコピー、AIが読めるテキスト、MCP経由の参照など同じ内容を届ける相手と経路が増えています。それぞれを別々に実装すると出力ごとに内容がずれたり更新時に直す場所が増えたりします。

Blumeは、この配信側の複雑さをまとめて引き受けようとしているオープンソースのドキュメントフレームワークです。今回はBlumeそのものを理解するために他にいいものが特にないのとたまたま自作していたmicroCMS CLI（mcms-cli）があったのでそのドキュメントサイトを作る意義自体はないですが、検証のイメージを掴むためには良さそうだったのでそれをドキュメントを題材としてmicroCMSのコンテンツをBlumeへ接続してみて実際に公開するところまで試しました。

公開した検証サイトはmcms-cli Docsから確認できます。

Blumeとは

BlumeはAstroとViteを土台にしたMarkdownファーストのドキュメントフレームワークです。
Hayden Bleaselさんが個人主導で開発・維持しているOSSです。

公式ドキュメントでは既存のドキュメントツールが抱えやすい負担として大きく二つの方向が説明されています。

1. オープンソースのフレームワークやスターターでは、コンテンツを書き始める前からアプリケーション一式を構築・保守する必要がある

2. マネージド型のサービスではすぐに整ったサイトを作れる一方、ビルドやホスティングをサービス側へ依存しやすい

Blumeが狙っているのはその中間です。

標準的な使い方ではMarkdownファイルをフォルダーへ置くだけでBlumeがドキュメントサイト全体を組み立てます。利用者は基本的にコンテンツだけを管理しながら、自分の環境へホストできます。さらに、必要になれば組み込みコンポーネントを置き換えたり、blume ejectで生成されたAstroプロジェクトを取り出したりできます。

MarkdownまたはMDXで本文を用意すると、ナビゲーション、全文検索、目次、パンくず、テーマ切り替えなどを備えたドキュメントサイトが生成されます。

ここまでなら「ドキュメント用のUIを自作しなくてよいツール」と捉えられます。ただ、Blumeが担当する範囲は画面づくりだけではありません。

つまりBlumeは一つのコンテンツ群を起点に人が読む画面と機械が読む出力を同じ構造から作るための基盤なのかと思います。

blume.config.tsがサイト全体の設計図になる

Blumeの設定は主にblume.config.tsへ書きます。今回の設定を要点だけ抜き出すと次のような形です。

import { defineConfig } from "blume";
import { microcmsSource } from "blume-source-microcms";

export default defineConfig({
  content: {
    sources: [
      {
        type: "custom",
        source: microcmsSource({
          serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN ?? "",
          apiKey: process.env.MICROCMS_API_KEY ?? "",
          endpoint: "documentation",
          fields: {
            title: "title",
            slug: "slug",
            body: "bodyMarkdown",
            description: "description",
          },
          body: { format: "markdown" },
        }),
      },
      {
        type: "github-releases",
        prefix: "changelog",
        owner: "mrmtsu",
        repo: "mcms-cli",
      },
    ],
  },
  ai: {
    llmsTxt: true,
    mcp: { enabled: true },
  },
  i18n: {
    defaultLocale: "ja",
    locales: [
      { code: "ja", label: "日本語" },
      { code: "en", label: "English" },
    ],
  },
  seo: {
    agentReadability: true,
    robots: true,
    sitemap: true,
    structuredData: true,
  },
  export: true,
  deployment: {
    adapter: "vercel",
    output: "server",
  },
});

この設定でコンテンツをどこから取得するか、どの言語を扱うか、AI向け出力やSEO関連の出力を有効にするか、どこへデプロイするかをまとめて指定しています。

deployment.outputをserverにしているのは今回MCPも有効にしたためです。通常のページ、llms.txt、ページ単位のMarkdownなどは静的に出力できます。一方、MCPやAsk AIはリクエストを受けて処理するエンドポイントが必要なので使う場合はサーバー出力が必要になります。

実際に公開したサイト

検証サイトにはmicroCMSから取得した日本語7ページと英語7ページを掲載しています。さらに、GitHub Releasesを変更履歴として読み込むContent Sourceも組み合わせ合計16のページを生成しました。

見た目を一から実装しなくてもドキュメントとして必要になる基本的なUIが揃います。画面幅に応じたレイアウトやライト・ダークテーマも含まれていました。

検索はタイトルだけでなく本文も対象になります。今回の規模では標準のOramaで十分に動作しました。より大きなサイト向けにはPagefindなどへ切り替える選択肢もあります。

同じ本文がWeb以外の形でも使える

Blumeらしさが分かりやすかったのは公開ページの外側にある出力です。たとえばインストールページに.mdを付けた/installation.mdへアクセスすると同じページをプレーンなMarkdownとして取得できます。画面上のCopy as Markdownも、このMarkdownをコピーします。

サイト全体については、次のファイルが生成されます。

• llms.txt: ページ構成と概要を一覧できる軽量な索引
• llms-full.txt: 公開ページの本文を一つにまとめたファイル

SEO向けにはタイトルやdescriptionなどのメタデータに加え、OG画像、robots.txt、サイトマップ、JSON-LDの構造化データを出力できます。AI向けにはMarkdownとllms.txt、MCP、コンテンツの利用方針を示すシグナルなどが用意されています。

ここは「Blumeを使えば検索順位やAIの回答精度が自動的に上がる」という意味ではなく、Blumeが整えるのは内容を発見・取得しやすくする技術的な経路なのかと思います。

そのため、記述の正確さ・情報設計・どの情報を公開するかは引き続きコンテンツを作る側の仕事として残るのかと考えます。

MCPとAsk AI

MCPを有効にするとAIエージェントはサイトを画面ごとスクレイピングするのではなくドキュメントの一覧取得、検索、ページ取得、ナビゲーション取得といった道具を介して情報を参照できます。今回、次の4つのツールが動くことをローカル環境で確認しました。

• list_pages: 公開ページを一覧する
• search_docs: ドキュメント内を検索する
• get_page: 指定したページをMarkdownで取得する
• get_navigation: ナビゲーション構造を取得する

またBlumeのEvalsを使い想定した6つの質問に対して該当ページを取得できるかも確認しました。今回はすべて期待したページへ到達できました。これは回答文そのものの品質評価ではなく、質問に必要な文書を取り出せるかの確認です。

Ask AIはサイト内に質問欄を置き、その場で回答を生成する機能です。こちらはBlumeだけで完結せず利用するAIモデルとプロバイダーの設定、認証、課金条件が関わります。今回もUIとリクエスト経路までは確認できましたが、Vercel AI Gateway側の利用条件を満たしていないので公開環境では無効にしています。Blumeが質問画面と文書の受け渡しを用意し、回答生成は接続先のAI基盤が担うと分けて考えると理解しやすいと思います。

Blumeのblume evalは個人的に面白く、AIがドキュメントだけを根拠に質問へ回答しその回答を期待事実ベースのLLM-as-a-Judgeで採点する機能という感じでした。さらにはCLIなのでCI上のドキュメント品質チェックとしても利用できそうです。

microCMSを組み合わせると実際どうなのか

BlumeはMarkdownファイルだけでも使えます。開発者が中心のチームならMarkdownをGitリポジトリで管理しGitHubのPull Requestでレビューする方法は扱いやすいでしょう。

一方で、Gitの操作やMarkdown記法に慣れていない人もドキュメントを更新する場合、編集という体験への参加が難しくなることがあると思っています。ここでmicroCMSを組み合わせると両者の担当を次のように分けることができると考えます。

microCMSが編集と運用の入口になり、Blumeが公開後の届け方を担当する構成です。CMSをドキュメントサイトへ置き換えるのではなく編集基盤と配信基盤を組み合わせています。

この役割分担がうまく機能すればたとえばサポート担当がFAQを更新し、開発者が技術的な内容を確認し、公開後は人もAIエージェントも同じ情報源を参照するといった流れを作れます。Web用とAI用に別々の原稿を持たずに済むので、公開経路が増えても内容のずれを抑えやすくなります。

microCMSとBlumeの間には変換層が必要

Blumeには外部CMSやリポジトリから本文を取り込むContent Sourcesという仕組みがあります。標準ではすでにSanityやNotion、GitHub Releasesなどに対応しています。

そこで、microCMSのAPIレスポンスをBlumeが扱う共通形式へ変換するアダプターを作りました。アダプターが行うことは、主に次の処理です。

1. microCMSのコンテンツAPIから一覧を取得する
2. タイトル、スラッグ、説明、公開状態などのフィールドを対応づける
3. 本文をMarkdownまたはMDXの文字列として渡す
4. Blumeが扱うページの形式へ揃えて返す

現在の検証サイトでは、microCMSのbodyMarkdownというテキストエリアにMarkdown文字列を保存しています。microCMSのAPIに「Markdownで返す」オプションがあるわけではなく、フィールド内の文字列をアダプターがMarkdown本文としてBlumeへ渡しています。

追加でリッチエディターのHTMLをMarkdownへ変換する処理は別のパッケージとして切り出しました。

実際にやってみて取り掛かる前はmicroCMS本体にMarkdown形式のレスポンスを追加すれば解決しそうと思っていたのですが、そうではないありませんでした。CMSごとにフィールド名、スラッグ、公開状態、並び順、画像の持ち方が異なるため本文以外もBlumeのページへ対応づける必要があります。CMS固有の違いを閉じ込める境界として変換層は必要でした。

複数のContent Sourceを一つのサイトへまとめられる

今回、microCMSだけでなくmcms-cliのGitHub ReleasesもContent Sourceとして読み込みました。リリース名、公開日、バージョン、本文がBlumeの変更履歴へ変換されます。ドキュメント本文はmicroCMS、変更履歴はGitHub Releasesというように情報の性質に合う管理場所を選びながら一つのサイトとして見せられます。

これはmicroCMSとBlumeを組み合わせる可能性を考えるうえで面白い点でした。すべてをCMSへ寄せる必要も、すべてをGitへ寄せる必要もありません。編集する人、レビュー方法、元データの所在に応じて管理場所を分け公開時にBlumeのコンテンツグラフへまとめられます。

多言語対応も同じ仕組みの上に載せられた

microCMSのAPIから日本語と英語のコンテンツを取得し、Blume側の言語ルーティングへ対応づけました。言語切り替え、言語ごとのナビゲーション、hreflangを含むSEO情報まで生成されます。

多言語対応で難しいのは、表示を切り替えるUIよりも、翻訳の有無、URLの対応、更新タイミングをどう管理するかです。Blumeは表示とルーティングを担当できますが、原文と翻訳の対応関係や翻訳レビューはCMS側の設計として考える必要があります。ここでも、Blumeが配信上の課題を引き受けコンテンツ運用の判断はmicroCMS側に残るという役割分担になりました。

まだまだ運用設計が必要な部分

機能を動かすところまではかなり確認できましたが本番運用にするなら次の検討が残ります。

• microCMSの更新をWebhookで検知し、いつ再ビルドするか
• 下書きを関係者だけが確認できるプレビュー環境
• API障害時に前回のキャッシュを使うか、ビルドを止めるか
• リッチエディター独自要素や画像をどこまでMarkdownで再現するか
• Ask AIで使うモデル、利用料金、レート制限、回答品質の監視

これらはCMSと公開基盤を接続したときに必要になる運用上の判断です。静的なMarkdownだけで運用する場合より考えることは増えますがその代わりに編集へ参加できる人を広げられます。

どのような場合に良さそうか

少人数の開発チームだけで更新しGitとMarkdownですでに困っていないならmicroCMSをあえて挟まずBlumeをそのまま使う構成がシンプルです。

一方、開発者以外も更新する、下書きや公開状態を管理したい、複数のプロダクトや言語へ広げたいといったような条件があるならmicroCMSを編集基盤として組み合わせる意味が出てきます。公開先では人向けの読みやすさだけでなくMarkdownやMCPを通じてAIからも同じドキュメントを参照できるようになります。

Blumeを試した現時点での見方

Blumeは単に整ったドキュメントUIを生成するツールではありませんでした。一つのコンテンツから、Web、検索、Markdown、SEO関連ファイル、AI向けファイル、MCPまで、用途の違う出力をまとめて作るフレームワークです。

microCMSと組み合わせるとその配信能力にCMSの編集体験と公開管理を加えることができます。やってみて結果的に接続にはアダプターが必要でしたが一度境界を作ればCMS固有のデータ構造をBlume本体から分離できます。今後microCMSのスキーマが変わった場合も主にアダプター側で吸収できます。

今回の検証で魅力を感じたのはAI向けに別のドキュメントを作るのではなく、人が読んでいるものと同じ情報源を別の経路でも届けられることです。AIから取得できる状態と、AIが正しく答えられる状態は同じではありません。それでも、まず同じ原稿へたどり着ける経路を揃えるところまでを少ない設定で形にできるのはBlumeの強みだと感じました。

参考資料

• Blume Introduction
• Blume Content Sources
• Blume AI
• Blume SEO
• 今回公開したmcms-cli Docs