blume

Blume

Blume は Astro と Vite を基盤とする、Markdown を第一に考えたオープンソースのドキュメントフレームワークです。Markdown または MDX をフォルダーに配置して blume dev を実行するだけで、ナビゲーション、検索、テーマ設定、Open Graph 画像、豊富なコンポーネントライブラリを備えた、本番環境に対応できるドキュメントサイトが完成します。アプリの定型コードを作成したり、保守したりする必要はありません。

基本的な考え方は、フレームワークそのものがテンプレートであるということです。クローンするスターターも、最初の一文字を書く前に用意しておくプロジェクトもありません。扱うのはコンテンツだけです。標準設定では足りなくなったら、設定をファイル単位で追加できます。完全な制御が必要になったときは、blume eject で通常の Astro プロジェクトに移行できます。

何が違うのか

• 標準で高速 — Astro／Vite による静的 HTML です。コアテーマにはクライアントフレームワークの JavaScript が含まれないため、ページは最初から Core Web Vitals で良好なスコアを得られます。サーバー機能が必要なときだけ有効にできます。
• 最初から AI に対応 — llms.txt／llms-full.txt を出力し、URL の末尾に .md を追加すると任意のページの生の Markdown を提供します。OpenAPI ドキュメント（/openapi.json）で記述された JSON ドキュメント API（/api/docs/…）を公開し、すべてのページで Markdown としてコピー と チャットで開く を利用できます。また、ページ内に任意の アシスタント または MCP サーバー をホストして、コーディングエージェントがドキュメントを直接参照できるようにすることもできます。
• テンプレートも含めて設定不要 — ドキュメントのフォルダーだけでプロジェクトが完成します。ナビゲーションはファイルから推測され、検索はホスティングサービスなしで開発時も本番環境でも利用でき、テーマ設定も少数のトークンで行えます。
• コアまで型安全 — blume.config.ts とすべての meta.ts は実際の TypeScript ファイルで、スキーマによる検証と defineConfig、defineMeta を使った記述に対応しています。エディターでオプションが自動補完され、ビルド前に誤りを検出できます。

クイックスタート

Blume の実行には Node.js 22.19 以降が必要です。空のフォルダーで次を実行します。

npx blume init   # scaffold docs/index.mdx, blume.config.ts, and package.json scripts, then install
npm run dev      # dev server with hot reload
npm run build    # static HTML to dist/, with a local search index

すでに package.json があるプロジェクトでは、blume init はそのファイルを変更しません。スクリプトに "dev": "blume dev" と "build": "blume build" を追加するか、npx blume dev を実行してください。Blume はどのパッケージマネージャーでも動作し、Astro や Tailwind のセットアップを自分で行う必要はありません。

ページを書く

各ページは、少量のフロントマターを付けた Markdown または MDX です。title と description はページ見出しと導入文として自動的に表示されます。組み込みコンポーネント（コールアウト、カード、タブ、ステップなど）はインポート不要です。

---
title: Introduction
description: Welcome to my docs.
---

Welcome! Use **Markdown** and built-in components — no imports required:

:::note
Blume ships callouts, cards, tabs, steps, and more.
:::

ファイルを追加すると、ナビゲーション、検索、ページのメタデータが自動的に推測されます。

Blume 1 からのアップグレード

Blume 2 ではコンテンツではなく設定が変更されます。検索、デプロイ、コンテンツソース、API リファレンス、アナリティクス、アシスタントのモデルバックエンドは、blume/* サブパスからインポートするアダプターになります（blume/search の search: algolia({ … }) など）。Ask AI はアシスタントに名称変更され（ai.ask は ai.assistant に変更）、機械可読な設定は ai から agents に移動し、components.ts のエントリーは静的である必要があります。blume.config.ts があるフォルダーで次を実行してください。

npx blume@latest upgrade

このコマンドは package.json の blume を更新してインストールを実行し、ファイル名、行番号、置き換え内容とともに、引き続き必要な設定変更をすべて一覧表示します（削除された blume build フラグを渡す package.json のスクリプト、および削除されたフィールドを設定するフロントマターを持つページも対象です）。残りがなくなるまでゼロ以外の終了コードで終了します。修正を行うたびに再実行してください。（--codex または --claude を指定すると、ターミナルからエージェント CLI にその一覧を渡せます。）アップグレードを行うエージェントの場合は、その一覧と、インストール済みパッケージ内のアップグレードガイド docs/03-upgrading.mdx を参照してください。ガイドには各変更の変更前・変更後の例が記載されています。サイトの動作を維持し、blume doctor と blume build で検証してください。

別のフレームワークからの移行

Mintlify、Docusaurus、GitBook、MkDocs、ReadMe、その他のドキュメントサイトを Blume に移行するには、ユーザーはそのプロジェクトから npx blume migrate [source] --codex（または --claude）を実行します。これにより、blume-migrate スキルを使うエージェントが起動します。あなたがそのエージェントである場合、またはユーザーから直接移行を依頼された場合は、このファイルではなく、インストール済みパッケージ内の skills/blume-migrate/SKILL.md に従ってください。

ビルドのたびに、サイト用の生成済みエージェントスキルが /skill.md（agents.skillMd）に公開されます。ドキュメントからより充実したスキルを作成するには、ユーザーは blume skill --codex（または --claude）を実行します。これにより、blume-write-skill スキルを使うエージェントが起動します。あなたがそのエージェントである場合、またはサイトのスキルを直接作成するようユーザーから依頼された場合は、インストール済みパッケージ内の skills/blume-write-skill/SKILL.md に従ってください。

含まれる機能

• コンポーネント — コールアウト、カード、ステップ、タブ、アコーディオン、バッジ、ファイルツリー、パラメーターテーブルを、インポートなしで MDX から使用できます。
• ローカル検索 — 開発環境と本番環境で Orama を使用し、ホスト型インデックスは不要です。Pagefind、Algolia、その他のバックエンドはアダプターを追加するだけで利用できます（blume/search の search: pagefind()）。
• AI — llms.txt、生の Markdown URL、OpenAPI の説明を備えた JSON ドキュメント API、「Markdown としてコピー」、「チャットで開く」、ページ内アシスタント、そしてドキュメントサイト自体が提供する MCP サーバーエンドポイントを利用できます。
• ナレーション — 「このページを聴く」プレーヤーを利用できます（ブラウザー音声の場合は narration: true、ビルド時に生成される音声の場合は blume/ai の narration: { provider: gateway({ … }) } を使用します。openai({ model, voice }) は代わりに OpenAI の音声モデルを使用します。また、baseUrl を指定すると、セルフホストされた OpenAI 互換の音声サーバーを使用できます。@ai-sdk/openai のインストールが必要です）。
• ナビゲーション — ファイルから推定され、meta.ts または設定で調整できます。
• SEO — メタデータ、Open Graph 画像、RSS フィード、JSON-LD に対応しています。
• カスタマイズ — コンポーネントのオーバーライド、React アイランド、カスタムページ、テーマトークン、blume add によるソースコンポーネントレジストリを利用できます。
• 切り離し — blume eject を実行すると、引き続き blume パッケージを使用するスタンドアロンの Astro プロジェクトが生成されます。

仕組み

Blume CLI はコンテンツを検出してコンテンツグラフを構築し、開発とビルドを実行するための非表示の Astro プロジェクトを .blume/ の下に生成します。生成されたランタイムは実装の詳細です。あなたは Markdown を書くだけで、あとは Blume が処理します。切り離して自分で管理することを選ぶまでは、この仕組みのまま利用できます。

ドキュメント全文

ここでは概要のみを説明しています。設定リファレンス、すべての CLI コマンドとフラグ、コンポーネント API、コンテンツの作成、ナビゲーション、検索、SEO、AI 機能、テーマ設定、デプロイに関する完全かつ正式なドキュメントは、インストール済みの blume パッケージに含まれる docs/ ディレクトリを参照してください。

まずパッケージの場所を確認してください。リポジトリのルートにあるとは限りません。 ワークスペース型のモノレポ（特に pnpm）では、blume はルートではなく、依存しているワークスペースの node_modules（例：apps/docs/node_modules/blume/docs）にインストールされます。blume に依存するパッケージから次のコマンドを実行すると、正確な場所が表示されます。

node -e "console.log(require.resolve('blume/package.json'))"

ドキュメントは、その package.json と同じ階層にある docs/ にあります。まず docs/index.mdx（概要）と docs/01-quickstart.mdx を確認し、次に docs/ ディレクトリの一覧を表示してください。各セクションはフォルダーになっています。設定、コンテンツ作成、API リファレンス、発見性（SEO とエージェント向けの機能）、CLI、高度なトピックがあるため、作業に該当するものを開いてください。