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

## 概要

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

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

## バージョニングの有効化

バージョニングは**デフォルトで無効**です。有効にするには、`zfb.config.ts`の`zudoDoc({...})`に`versions`配列を追加します：

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    // ...
    versions: [
      {
        slug: "1.0",
        label: "1.0.0",
        docsDir: "src/content/docs-v1",
        locales: {
          ja: { dir: "src/content/docs-v1-ja" },
          de: { dir: "src/content/docs-v1-de" },
        },
        banner: "unmaintained",
      },
    ],
  }),
);
```

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

```ts
versions: false,
```

## 設定リファレンス

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

| プロパティ | 型 | 必須 | 説明 |
|----------|------|----------|-------------|
| `slug` | string | はい | URLパスで使用されるバージョン識別子（例：`"1.0"`、`"v2"`） |
| `label` | string | はい | バージョン切り替えに表示されるラベル（例：`"1.0.0"`） |
| `docsDir` | string | はい | このバージョンの英語ドキュメント用コンテンツディレクトリ |
| `locales` | `Record<string, { dir: string }>` | いいえ | ロケールごとのコンテンツディレクトリ；各エントリは`{ dir }`のみ（`label`なし） |
| `banner` | `"unmaintained"` \| `"unreleased"` \| `false` | いいえ | バージョンページに表示されるバナーの種類 |

## ディレクトリ構造

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

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

[Dynamic content unavailable in text export]

各バージョンディレクトリは存在し、有効なMDXコンテンツファイルを含んでいる必要があります。zudo-docは各バージョンに対して個別のzfbコンテンツコレクションを作成するため、ディレクトリが存在しないとビルドエラーが発生します。



## 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.0（ドイツ語）：** `/v/1.0/de/docs/getting-started/introduction/`

## バージョン切り替え

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

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

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

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

## バージョン一覧ページ

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

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

各バージョンのドキュメントリンク（および「最新ドキュメント」リンク）は、`entryDocSlug`で設定されたルートスラッグを指します：

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    // ...
    entryDocSlug: "getting-started",
  }),
);
```

`entryDocSlug`は先頭・末尾にスラッシュを含まないルートスラッグです（例：`"getting-started"`、`"overview/getting-started"`）。省略した場合のデフォルトは`"getting-started"`で、実行時のバリデーションは行われません。存在しないスラッグを指定した場合、ビルドは失敗せず単に404リンクになります。

## バージョンバナー

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

### Unmaintained（メンテナンス終了）

```ts
banner: "unmaintained",
```

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

### Unreleased（未リリース）

```ts
banner: "unreleased",
```

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

### バナーなし

```ts
banner: false,
```

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

[Dynamic content unavailable in text export]

更新されなくなったアーカイブバージョンには`"unmaintained"`を、まだリリースされていない機能のドキュメントには`"unreleased"`を使用してください。



## マルチロケール対応

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

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

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

## 新しいバージョンの作成

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

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

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

2. 該当する場合は**設定した各ロケールディレクトリ**もコピー：

   ```bash
   cp -r src/content/docs-ja src/content/docs-v2-ja
   cp -r src/content/docs-de src/content/docs-v2-de
   ```

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

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

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

[Dynamic content unavailable in text export]

`versions`配列は古いバージョンまたはプレリリースバージョンのみを定義します。現在の最新バージョンは常にメインの`docsDir`を使用し、配列には含まれません。