コンテンツにスキップ
Blume
日本語
EnglishDeutschहिन्दी日本語Português
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

バージョニング

リリースごとにドキュメントのスナップショットを凍結し、バージョン切り替え、最新版への正規URL指定によるSEO、バージョン単位の検索、バージョン対応のエージェントインターフェースを実現します。

Blume は、実際のリリース運用に沿った形でドキュメントをバージョン管理します。最新のドキュメントはコンテンツのルートに置かれ、プレフィックスのないきれいな URL を持ちます。そして過去の各バージョンは、それぞれのフォルダに凍結されたスナップショットとして保存されます。リリース時にスナップショットを作成すれば、切り替え UI、「古いバージョン」の通知、検索のスコープ設定、SEO、エージェントインターフェースは Blume が自動で構成します。これはオプトイン方式です。versions ブロックがなければ、何も変わりません。

有効にする

現在のドキュメントとアーカイブ済みスナップショットを指定する versions ブロックを追加します:

versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}

current は、切り替え UI におけるプレフィックスなしのツリーのラベルを設定します（badge は任意です）。アーカイブされた各エントリの id は、スナップショットのディレクトリ名であると同時に URL セグメントでもあります。id は文字で始める必要があり（1.0 ではなく v1.0）、これにより数値の並び順プレフィックスと衝突することがなくなります。アーカイブ済みバージョンは新しいものから順に並べてください。その順序がそのまま切り替え UI の順序になります。

バージョンを作成する

リリース時には、次のコマンド 1 つで現在のドキュメントを凍結できます:

blume version v1.0

このコマンドは、コンテンツツリーを docs/v1.0/ にコピーし（既存のスナップショットは除外されます）、コピー内のルート絶対リンクをスナップショット内に留まるように書き換え（/guides/x は /v1.0/guides/x になります。フェンス付きコードおよびインラインコードは変更されません）、blume.config.ts に id を登録します。設定ファイルが自動編集できない形になっている場合は、貼り付け用のエントリを出力します。コピー対象のツリーに含まれないページへのリンク（生成された API リファレンス、変更履歴などのリモートソース）は、スナップショットにそのコピーが存在しないため、ライブのページを指したままになります。id を付けずに blume version を実行すると、設定済みのバージョン一覧が表示されます。

新しいディレクトリは、他のコンテンツと同様に確認してコミットしてください。反映するには blume dev を再起動します。

docs/
  index.mdx               ->  /              (latest)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (frozen)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart

アーカイブ済みとは凍結を意味します。 今後の編集はライブのツリーに対して行ってください。スナップショットは当時のままのドキュメントです。Blume はその前提に基づいて動作します。スナップショットは独自のフォルダメタデータと翻訳を保持し、blume translate がスナップショットを再翻訳することはありません。また、設定で明示したサイドバーは現在のドキュメントにのみ適用され、スナップショットのサイドバーは常にそれ自身のファイルから生成されます。

切り替え UI と通知

バージョンを設定すると、ヘッダーにバージョンのドロップダウンが自動的に追加されます。切り替え時には、対象バージョンに同じページが存在すればそのページに、存在しなければそのバージョンのルートに遷移します（常にルートに遷移させるには switcher.redirect: "root" を設定します）。navigation.selectors で独自の kind: "version" セレクターを宣言した場合は、そちらが自動生成のものを置き換えます。

アーカイブ済みのすべてのページには、そのページのライブ版へのリンクを含む「最新版へ移動」の通知も表示されます（非表示にはできません）。バージョンごとにカスタマイズまたは無効化できます:

archived: [
  { id: "v1.0", banner: "These docs cover the 1.x SDK." },
  { id: "v0.9", banner: false },
];

SEO

古いドキュメントは検索エンジンにとって格好の落とし穴です。古いページが最新のページより上位に表示されたり、両者が競合したりします。Blume は、SEO ガイドが推奨しながらも他のどのドキュメントフレームワークも自動化していない解決策をデフォルトとしています。アーカイブ済みページはインデックス可能なまま維持されますが、最新版の対応ページを正規 URL として宣言します。これによりライブのページが権威あるページとなり、一方でそのバージョンにしか存在しないコンテンツ（最新ドキュメントにはすでに存在しないページ）は自己正規 URL によって引き続き見つけられます。

バージョンごとに異なる扱いを選択できます:

archived: [
  { id: "v1.0" }, // canonical → latest (default)
  { id: "v0.9", canonical: "self" }, // every page authoritative
  { id: "v0.8", noindex: true }, // deindexed entirely
];

サイトマップもこれに従います。正規 URL がライブの対応ページを指しているアーカイブ済みページは除外され、noindex のバージョンは丸ごと除外され、そのバージョンにしかないページは掲載されたままになります。ページ自身の seo.canonical フロントマターは常に優先されます。

検索

検索ダイアログは、閲覧中のバージョンに結果のスコープを絞り込み、言語トグルの隣に「すべてのバージョン」トグル（読者ごとに記憶されます）を表示します。バージョンをまたぐヒットは、結果の行にバージョン名が表示されます。Orama（デフォルト）、FlexSearch、Algolia、Typesense はいずれもこのスコープ設定に対応しています。ホスト型のレコードは version ファセットを持ち、現在のドキュメントは "current" としてアップロードされます。一方 Pagefind はスコープ設定に対応しておらず、ロケールの挙動と同様の扱いになります。

エージェント

エージェントインターフェースはバージョンを認識します。これは他のどのドキュメントフレームワークにもない機能です:

  • MCP の search_docs および list_pages ツールは、デフォルトで現在のドキュメントを対象とし、version を受け付けます。値はアーカイブ済みの id（"v1.0"）または "all" です。get_navigation はリクエストに応じてアーカイブ済みスナップショットのツリーを返します。
  • llms.txt は、現在のドキュメントの後ろにアーカイブ済みバージョンのセクションを配置し、1.0 (archived) のようにラベル付けします。これにより、インデックスを読むエージェントはどのドキュメントが凍結されているかを把握できます。
  • llms-full.txt は現在のバージョンのみを対象とします。フラットなダンプに同じページの凍結コピーが混在することはありません。
  • 生の Markdown ミラー（.md の URL）は、他のルートと同様に、すべてのバージョンのページに存在します。

i18n との併用

バージョニングは国際化と組み合わせられます。ディスク上ではバージョンフォルダが最も外側になり、スナップショットはその中にロケールフォルダを自然に含みます。一方 URL では、サイトの他の部分と同様にロケールが最も外側になります:

docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x

ロケールのフォールバックは各バージョン内で機能します。未翻訳のスナップショットページは、ローカライズされた URL でフォールバックロケールのコンテンツを表示し、hreflang の代替指定はバージョンごとにグループ化されます。バージョン id は設定済みのロケールコードと衝突してはなりません。Blume はそのような設定を明確に拒否します。

バージョン管理されないもの

バージョニングの対象はドキュメントのコンテンツツリーです。ブログ、変更履歴、OpenAPI 仕様から生成される API リファレンス、カスタムページは常に最新版のみです。さらに知っておくべき挙動が 2 つあります。ヘッダーのタブは現在のドキュメントに対して定義されるため、アーカイブ済みツリー内ではサイドバーはタブによるスコープなしで表示されます。また、大規模サイトでは、各スナップショットが完全なコピーである点に注意が必要です。コンテンツ、検索インデックスのエントリ、ナビゲーションデータはすべてバージョンごとに増加します。

最終更新 2026年8月15日

このページは役に立ちましたか？