BlumeとmicroCMSの連携をしてみた

Blumeとは

Blumeは、MarkdownやMDXからドキュメントサイトを生成するOSSフレームワークです。
AstroとViteを基盤にしており、Markdownファイルを用意すれば、ナビゲーションや検索を備えたサイトを構築することができます。

最小構成では、フォルダにMarkdownを置いてビルドします。

docs/
├── index.md
├── getting-started.md
└── faq.md

blume build

これだけを見ると、Blumeは一般的なドキュメントサイトジェネレーターの一つに見えますが実際は、Webサイトとして必要になる検索、ナビゲーション、コードのシンタックスハイライト、SEO、OG画像、コンポーネントなどが含まれています。

さらにそれだけではなく、AIが利用しやすい経路もまとめて生成してくれます。

記事執筆時点では、llms.txtとページごとのMarkdownは標準で利用でき、Ask AIとMCPは必要に応じて有効にする機能です。Ask AIはドキュメント内の検索結果を根拠に回答し、MCPではAIクライアントがドキュメントを検索・取得できます。

この構成から、私はBlumeを「MarkdownをHTMLへ変換するツール」よりも、「一つの原稿を、人とAIがそれぞれ利用しやすい形で届けるためのフレームワーク」と捉えました。

一つの原稿
    ↓
  Blume
    ├── Webページ
    ├── サイト内検索
    ├── Markdown
    ├── llms.txt
    ├── Ask AI
    └── MCP

Blumeが自動生成する画面と配信形式を見てみる

今回の検証では自作しているmcms-cliというmicroCMSのCLIドキュメントをBlumeで構築してみました。

コンテンツを渡した後の画面では、本文だけでなく、左側のナビゲーション、ページ内目次、検索、前後ページへの移動、Markdownのコピーなどがまとまって表示されます。

この検証では、サイドバーや検索画面、目次、Markdownコピーボタンを個別には実装していません。

Blumeが取り込んだページのタイトル、slug、見出し、並び順などを使って、ドキュメント向けのUIを組み立ててくれています。

画面として見える機能だけでなく、同じページをMarkdownとして取得する経路や、サイト全体をAIが把握するためのllms.txtも生成されます。

検索画面もBlume側で用意される

画面右上の検索を開くと、ページのタイトルだけでなく本文も対象にして候補が表示されます。検索結果の一覧と内容のプレビューまで含まれており、この検索画面も個別に実装していません。

同じ原稿から複数のデータが生成される

Blumeの全体像は、ドキュメントの画面だけを見るよりも、ビルド後のデータを見ると把握しやすくなります。今回の検証環境で実際に生成されたものを一部抜き出してみます。

ページごとのMarkdown

通常のWebページとは別に、同じ内容を.mdで取得できます。次はトップページから生成されたindex.mdの一部です。

---
title: mcms-cli
description: microCMSのコンテンツやスキーマを、AIやCIから安全に扱うための非公式CLIを紹介します。
sidebar:
  order: 1
noindex: false
---

`mcms-cli`は、microCMSのContent APIとManagement APIを
コマンドラインから操作するための非公式CLIです。

## 何を解決するツールか

このMarkdownは、ページにある「Copy as Markdown」がコピーする内容でもあります。ブラウザ向けのHTMLと、コピーやAI入力に使えるMarkdownを、別々の原稿として管理する必要はありません。

サイト全体の索引になるllms.txt

llms.txtには、サイト名、説明、各ページのURLと概要がまとまります。今回生成されたファイルは次のような内容でした。

# mcms-cli Docs

> microCMSで管理するmcms-cliのドキュメントを、
> Blumeで人とAIへ配信する検証サイト。

## Docs

- [mcms-cli](/): microCMSのコンテンツやスキーマを、AIやCIから安全に扱うための非公式CLIを紹介します。
- [インストールと認証](/installation): mcms-cliをインストールし、認証する方法を説明します。
- [コンテンツを安全に操作する](/content-operations): 書き込み前の検証と実行手順を説明します。
- [スキーマと型を管理する](/schema-and-types): スキーマの取得・比較・型生成を説明します。

さらにllms-full.txtには、ページ一覧だけでなく各ページのMarkdown本文もまとめられます。

AI向けの入口を示すagent-readability.json

agent-readability.jsonには、このサイトで利用できるAI向けの出力が記録されます。今回の設定では、ページごとのMarkdown、llms.txt、llms-full.txtが含まれていました。

{
  "artifacts": {
    "markdown": {
      "contentNegotiation": "text/markdown",
      "pattern": "/{route}.md"
    },
    "llmsFullTxt": "/llms-full.txt",
    "llmsTxt": "/llms.txt"
  },
  "generator": "blume@1.1.4",
  "name": "mcms-cli Docs"
}

静的ビルドの出力

ビルド後のディレクトリには、Webページ、検索用データ、Markdown、AI向けファイルが並びます。実際の出力を役割ごとに整理すると、次のようになります。

dist/
├── index.html                 # 人が読むWebページ
├── installation/index.html   # 各ドキュメントページ
├── blume-search.json         # サイト内検索のデータ
├── index.md                  # ページのMarkdown版
├── index.mdx                 # ページのMDX版
├── llms.txt                  # サイト構造とページ一覧
├── llms-full.txt             # 全ページのMarkdown本文
├── agent-readability.json    # AI向け出力の案内
└── robots.txt                # クローラー向けの方針

このように見ると、Blumeが用意するのはドキュメントの見た目だけではありません。一つの原稿から、Webページ、検索、コピー可能なMarkdown、サイト全体の索引、AI向けの案内までを同じビルドでそろえるところまでが含まれています。

ドキュメントをAIへ届けようとすると配信経路が増えていく

人向けのドキュメントサイトだけであれば、MarkdownをHTMLへ変換し、検索とナビゲーションを付けることで多くの要件を満たせます。

AIにも同じ内容を利用してもらおうとすると、考えることが増えます。Webページから本文を抽出するのか、Markdownを公開するのか、サイト全体の索引を用意するのか、検索APIやMCPを作るのか。ページ内に質問UIを置くなら、検索結果をどのようにモデルへ渡すかも決めなければなりません。

これらを別々に実装すると、Webサイト用の原稿、AIへ渡すデータ、検索インデックスの間に差が生まれやすくなります。Webページは更新されたのに、AIが参照するデータは古いままという状態も起こりえます。

Blumeが扱っている課題は、単に「AI機能を付けること」ではないように見えました。一つの原稿を基準にして、利用者ごとに異なる配信経路を同じビルドの中で作ることです。

たとえば、あるガイドを更新してBlumeをビルドすると、Webページだけでなく、そのページのMarkdownやサイト全体のllms-full.txtにも更新が反映されます。MCPやAsk AIも、同じドキュメント群を検索対象にできます。原稿を経路ごとに複製しないため、内容のずれを抑えやすくなります。

「AIが読める」と「AIが正しく使える」は分けて考える

ここで少し注意したいのは、MarkdownやMCPを用意すれば、AIが必ず正しい回答を返すわけではないことです。

Blumeは、AIが情報へアクセスするための経路を整えます。一方、原稿に必要な説明がなければ答えは見つかりません。古い情報が残っていれば、古い内容を根拠にする可能性もあります。似たページが複数あれば、どれを採用するかも評価が必要です。

そのため、Blumeが減らしてくれるのは、機械可読なファイルや検索手段を個別に用意する負担だと考えています。コンテンツの正確さ、更新頻度、公開範囲、AIの回答品質は、引き続き運用側で向き合う領域です。

この線引きがあるからこそ、CMSとの組み合わせを考える意味が出てきます。AI向けの出口だけでなく、その手前にある原稿の作成や更新をどう支えるかという話です。

Blumeは原稿を書く場所を固定していない

Blumeは、標準ではローカルのMarkdownやMDXを読み込みます。ただし、原稿の置き場所はファイルシステムだけに限られていません。

Content Sourceという仕組みを使うと、リモートリポジトリ、Sanity、Notion、GitHub Releasesなどから原稿を取得できます。複数のSourceを一つのサイトへ混在させることもできます。対応していないバックエンドは、共通のインターフェースを満たすカスタムSourceから接続できます。

Content Sourceは、外部サービスのデータをBlumeのページへ翻訳する取り込み口です。CMSごとに異なるフィールドや本文形式を、Blumeが扱えるMarkdownまたはMDXとメタデータへ揃えます。

CMSやリポジトリごとのデータ
            ↓
      Content Source
            ↓
Blumeが扱えるページとメタデータ

この仕組みがあることで、Blumeを使うために、すべての原稿をGit管理のMarkdownへ移す必要はありません。原稿の正本をCMSに置いたまま、Blumeを配信側として使う構成も選べます。

microCMSとBlumeは担当する場所が異なる

Blumeには、ドキュメントを届けるための機能がまとまっています。ただし、複数の編集者が管理画面で原稿を書き、レビューし、公開を管理するCMSではありません。

microCMSは反対に、コンテンツを作成・管理し、APIから提供することを得意とするヘッドレスCMSです。管理画面、リッチエディター、レビュー、権限、公開状態、Webhookなどを使って、原稿が公開されるまでの流れを組み立てられます。表示するWebサイトは、利用する側で用意します。

両者を組み合わせると、それぞれの担当は次のように分けられます。

microCMS
原稿の作成、レビュー、公開
             ↓
       コンテンツAPI
             ↓
          Blume
Web、検索、Markdown、llms.txt、MCP
             ↓
         人とAI

microCMSが原稿の編集基盤、Blumeがドキュメントの配信基盤になる構成です。どちらかがもう一方を置き換えるというより、CMSとドキュメントフレームワークを前後に並べる考え方です。

この組み合わせで変わりそうなこと

ドキュメントの更新に参加できる人が広がる

MarkdownをGitで管理する方法は、開発者にとって扱いやすく、コードとドキュメントを同じレビュー工程へ載せられます。一方、Gitの操作やMarkdownの記法に慣れていない人が更新するには、参加のハードルになることがあります。

microCMSを前段に置けば、管理画面から原稿を書き、プレビューやレビューを経て公開できます。サポート担当者や編集者が気づいた修正を反映し、開発者はBlumeの構成やデプロイを管理する、といった役割分担も考えられます。

誰にとってもCMSの方がよいという話ではありません。開発者だけで運用する小規模なドキュメントなら、MarkdownをGitで管理する方が単純です。microCMSを組み合わせる価値は、更新に関わる人や承認工程が増えたときになのかと思います。

すでにCMSにあるコンテンツへ新しい出口を加えられる

microCMSには、マニュアル、FAQ、ヘルプ、用語集など、ドキュメントとして再構成できるコンテンツを保存できますし、導入事例としてもあります。これまではコンテンツAPIから独自のWebサイトを作ることが主な出口でした。

Blumeとつなぐと、同じコンテンツからドキュメントサイトを作り、ページごとのMarkdownやllms.txtも生成できます。必要であれば、Ask AIやMCPも追加できます。

ここで変わるのは、コンテンツの用途です。ブラウザで表示するためのデータに加えて、チャットUIやAIエージェントが情報を探すときの参照元にもなります。microCMSに蓄積された原稿を、別のAI用データベースへ手作業で複製せずに使える可能性があります。

複数の正本を一つのドキュメントサイトへまとめられる

すべてのドキュメントをmicroCMSへ移す必要もありません。Blumeは複数のContent Sourceを組み合わせられるため、説明記事はmicroCMS、SDKのガイドはリポジトリ内のMarkdown、APIリファレンスはOpenAPI、更新履歴はGitHub Releasesといった分担ができます。

原稿の性質に合った場所を正本として選びながら、読者からは一つのドキュメントサイトとして見せる構成です。AI向けの出力も、Blumeが取り込んだページ群をもとに生成されます。

CMSかGitかを一つに決めるのではなく、どの種類の情報をどこで更新するのが自然かを選べる点は、Content Sourceを使う大きな理由になりそうです。

公開操作とドキュメントの更新をつなげられる

運用としては、microCMSでコンテンツを公開したときにWebhookを送り、Blumeのビルドとデプロイを実行する流れが考えられます。

microCMSで公開
      ↓ Webhook
Blumeをビルド
      ↓
WebとAI向けの出力を更新

この場合、編集者はmicroCMS上で公開を判断し、その結果がWebページとAI向けの経路へ反映されます。下書きプレビューを用意するなら、microCMSの下書きデータをBlumeのプレビュービルドへ渡す処理も必要です。

公開操作を起点に複数の配信物を同時に更新できれば、「AI向けデータだけ更新を忘れる」という分断は減らせそうです。

microCMSがMarkdownを返せば解決するという話ではなかった

microCMSのリッチエディターは、コンテンツAPIからHTMLを文字列で返します。Markdownを中心に扱うBlumeへ渡すには、HTMLをMarkdownへ変換する処理が必要になります。

それなら、microCMSがMarkdownを返す機能を持てば直接つながるのではないかと最初は考えました。検証してみると、本文がMarkdownになるだけでは接続全体は完了しませんでした。

CMSのJSONには、タイトル、URLに使うslug、本文、更新日時、並び順、公開状態などが含まれます。Blume側では、それぞれをページのメタデータへ対応づける必要があります。記事が増えれば、APIのページネーションや重複slugの検査も必要です。

Markdownで返せれば本文変換の負担は減ります。ただし、CMS固有のデータをBlumeのページへ揃えるContent Sourceの役割は残ります。

この点は、microCMSに限った話ではなくBlumeに標準対応しているSanityではPortable TextをMarkdownへ変換し、NotionではブロックツリーをMDXへ変換しています。CMSとドキュメントフレームワークの間には、それぞれのデータモデルを翻訳する薄い層が置かれています。

microCMSとの連携を考えるなら、microCMS全体のレスポンス形式をBlumeへ寄せるより、BlumeのContent Sourceとして変換を担う方が、役割の境界は分かりやすいと感じました。

実際につないでみた

microCMS向けのContent Sourceを試作してみました。リッチエディターを使う場合に備えて、HTMLをMarkdownへ変換する処理も分けて用意しました。

アダプターでは、microCMSのフィールドを設定で対応づけます。実装の中心は、次のような薄い設定です。

microcmsSource({
  serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN,
  apiKey: process.env.MICROCMS_API_KEY,
  endpoint: "documentation",
  fields: {
    title: "title",
    slug: "slug",
    body: "body",
    lastModified: "revisedAt",
  },
  body: {
    format: "richEditor",
  },
});

Webページ、Markdown、MDX、llms-full.txtまで生成できました。

この結果から言えるのは、microCMSを原稿の正本にしたまま、Blumeの配信機能へつなぐ構成は技術的に成立するというところまでです。

まだ確かめていないこと

接続できたことと、継続して運用できることは別の話です。実運用を考えるなら以下の点などを確認する必要があるのかと思います。

• microCMSの下書きをBlumeでどのようにプレビューするか
• 公開後のビルド失敗をどのように知らせるか
• API障害時に前回の正常な出力を維持するか
• 削除・非公開・URL変更を各出力へ正しく反映できるか
• AIへ見せたくないページをどの段階で除外するか
• Ask AIやMCPが、実際の質問へ十分に答えられるか

とくに公開範囲には注意が必要です。ページのMarkdownやllms-full.txtを公開すれば、HTMLとは別の経路からも本文へアクセスできます。もともと公開情報であれば問題になりにくい一方、会員向けや社内向けの情報では、認証や出力対象の設計が欠かせません。

また、llms.txtを公開しただけで、すべてのAIサービスが必ず参照するわけではありません。どの経路が実際に使われ、回答品質へどう影響するかは、対象のAIクライアントと質問を決めて評価する必要があります。

どのようなケースに合いそうか

microCMSとBlumeの組み合わせは、すでにmicroCMSでマニュアルやFAQを管理しており、それをドキュメントサイトとAI向けの参照元へ展開したい場合に合いそうです。

複数の職種が更新に関わり、管理画面での編集やレビューが必要な場合にも検討できます。

原稿の運用はmicroCMSへ寄せつつ、開発者はBlumeによる表示、検索、AI向け配信を管理できます。

反対に、開発者だけで小規模に運用し、コードと同じGitレビューで問題がないなら、BlumeへMarkdownを直接置く方が断然単純です。

CMSを加えると、API接続、プレビュー、Webhook、ビルド監視などの余分な運用も増えます。

microCMSの先にある配信先を考える

Blumeを見ていて興味深かったのは、ドキュメントサイトの完成をブラウザ上の画面だけに置いていないことでした。同じ原稿をMarkdownとして取得でき、サイト全体の索引を用意し、必要ならAIから検索できる接続口も持てます。

microCMSを組み合わせるとその配信の手前に管理画面での編集、レビュー、公開管理を置くことができます。

CMSで原稿を整え、Blumeが人とAIへ届けるという感じで考えると、microCMSはWebサイトへデータを渡すだけでなく、複数の利用者へ知識を供給する起点になりえます。

参考資料

• Blume公式サイト
• Blume Content sources
• Blume AI
• Blume GitHubリポジトリ
• microCMS リッチエディタの操作方法
• microCMS レビュー
• microCMS コンテンツのWebhook