バージョニング

バージョンプレフィックス付きURLとバージョン切り替えで複数バージョンのドキュメントを管理

zudo-docは、ドキュメントの複数バージョンを並行して管理することをサポートしています。バージョニングを有効にすると、古い（またはプレリリース）バージョンはバージョンプレフィックス付きURLで配信され、バージョン切り替えがレイアウトに表示されます。

概要

バージョニングにより以下が可能になります：

• 最新のドキュメントを通常通り/docs/...で提供
• 古いバージョンを/v/{version}/docs/...で提供
• バージョン切り替えでユーザーがバージョン間を移動可能
• バージョンバナーで古いまたは未リリースのコンテンツを表示

バージョニングの有効化

バージョニングはデフォルトで無効です。有効にするには、src/config/settings.tsにversions配列を追加します：

export const settings = {
  // ...
  versions: [
    {
      slug: "1.0",
      label: "1.0.0",
      docsDir: "src/content/docs-v1",
      locales: {
        ja: { dir: "src/content/docs-v1-ja" },
      },
      banner: "unmaintained",
    },
  ],
};

バージョニングを無効にするにはversionsをfalseに設定（または省略）します：

versions: false,

設定リファレンス

各バージョンエントリは以下のプロパティを受け付けます：

ディレクトリ構造

各バージョンのコンテンツは独自のディレクトリに格納されます。最新（現在の）バージョンはデフォルトのdocsDirを使用し、古いバージョンは設定で指定されたディレクトリを使用します：

src/content/
├── docs/                # 最新バージョン（デフォルト）
├── docs-ja/             # 最新バージョン — 日本語
├── docs-v1/             # バージョン1.0 — 英語
├── docs-v1-ja/          # バージョン1.0 — 日本語
├── docs-v0.9/           # バージョン0.9 — 英語
└── docs-v0.9-ja/        # バージョン0.9 — 日本語

URL構造

最新バージョンはデフォルトのドキュメントURLで配信されます。古いバージョンは/v/{slug}/プレフィックスを使用します：

• 最新： /docs/getting-started/introduction
• バージョン1.0： /v/1.0/docs/getting-started/introduction
• バージョン0.9： /v/0.9/docs/getting-started/introduction

ロケールを使用する場合、ロケールプレフィックスはバージョンプレフィックスの後に配置されます：

• 最新（日本語）： /ja/docs/getting-started/introduction
• バージョン1.0（日本語）： /v/1.0/ja/docs/getting-started/introduction

バージョン切り替え

1つ以上のバージョンが設定されると、バージョン切り替えがヘッダーバーとドキュメントコンテンツエリアの両方に自動的に表示されます。現在のバージョンラベルが表示され、最新バージョンを含むすべての利用可能なバージョンへの切り替えリンクが提供されます。

切り替え時は現在のページスラッグが保持されるため、選択したバージョンでも同じトピックのページに遷移します。

古いバージョンにページが存在しない場合、そのバージョンのリンクは自動的に無効化（グレーアウトしてクリック不可）され、404ページへのリンクにはなりません。これはビルド時に各バージョンのコンテンツディレクトリをスキャンすることで判定されます。

ドロップダウンの下部には**「すべてのバージョン」**リンクがあり、バージョン一覧ページに移動できます。

バージョン一覧ページ

/docs/versions/（日本語は/ja/docs/versions/）に専用のバージョン一覧ページが自動生成されます。このページには、設定されたすべてのバージョンがラベル、ステータスバッジ、ドキュメントリンクとともに一覧表示されます。Docusaurusのバージョンページと同様の構成です。

このページはsettings.tsのversions配列から自動生成されます。手動でのメンテナンスは不要で、設定でバージョンを追加・削除すると一覧ページも自動的に更新されます。

バージョンバナー

各バージョンは、バージョンの状態をユーザーに知らせるバナーをすべてのページの上部に表示できます。2種類のバナーが利用可能です：

Unmaintained（メンテナンス終了）

banner: "unmaintained",

ユーザーが古いバージョンのドキュメントを閲覧していることを示す警告スタイルのバナーを表示し、最新バージョンへのリンクを含みます。

Unreleased（未リリース）

banner: "unreleased",

ユーザーが未リリースバージョンのドキュメントを閲覧していることを示す情報スタイルのバナーを表示し、最新安定バージョンへのリンクを含みます。

バナーなし

banner: false,

そのバージョンのバナーを無効にします。bannerを省略した場合のデフォルトです。

マルチロケール対応

各バージョンは、メインのロケール設定とは独立して独自のロケールディレクトリを定義できます：

versions: [
  {
    slug: "1.0",
    label: "1.0.0",
    docsDir: "src/content/docs-v1",
    locales: {
      ja: { dir: "src/content/docs-v1-ja" },
    },
    banner: "unmaintained",
  },
],

各バージョンとロケールの組み合わせに対して、zudo-docは個別のコンテンツコレクション（例：docs-v-1.0-ja）を作成し、対応するページルートを生成します。

新しいバージョンの作成

現在のドキュメントを新しいバージョンとしてアーカイブする準備ができたら：

1. 現在のコンテンツディレクトリを新しいバージョンディレクトリにコピー：

   cp -r src/content/docs src/content/docs-v2

2. 該当する場合はロケールディレクトリもコピー：

   cp -r src/content/docs-ja src/content/docs-v2-ja

3. 設定にバージョンを追加：

   versions: [
     {
       slug: "2.0",
       label: "2.0.0",
       docsDir: "src/content/docs-v2",
       locales: {
         ja: { dir: "src/content/docs-v2-ja" },
       },
       banner: "unmaintained",
     },
     // ...既存のバージョン
   ],

4. 現在のドキュメントを更新 — src/content/docs/内のファイルが最新バージョンとなります。新しいリリースに合わせて必要に応じて更新してください。