zudo-docはDocusaurusにインスパイアされたナビゲーション階層をサポートしています：

- **ヘッダーナビゲーション** — サイトヘッダーのトップレベルタブ。オプションでドロップダウンメニューを含む
- **サイドバーカテゴリ** — サイドバーの折りたたみ可能なグループ
- **サイドバーアイテム** — カテゴリ内の個別ページ

[Dynamic content unavailable in text export]

このページは**左側のタブ**について説明しています。右側クラスタ(外観メニュー・GitHub リンクなど)の設定は別ページ [ヘッダー右側アイテム](https://zudo-doc.takazudomodular.com/ja/docs/guides/header-right-items) を参照してください。



## 設定

`zfb.config.ts`でヘッダーナビゲーションアイテムを定義します。アイテムはフラットリンクまたはネストされた子を持つドロップダウン親のいずれかです：

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    // ...
    headerNav: [
      // Flat link (no dropdown)
      { label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },

      // Dropdown parent with children
      {
        label: "Learn",
        labelKey: "nav.learn",
        path: "/docs/guides",
        categoryMatch: "guides",
        children: [
          { label: "Guides", labelKey: "nav.guides", path: "/docs/guides", categoryMatch: "guides" },
          { label: "Components", labelKey: "nav.components", path: "/docs/components", categoryMatch: "components" },
        ],
      },

      { label: "Reference", labelKey: "nav.reference", path: "/docs/reference", categoryMatch: "reference" },
    ],
  }),
);
```

## プロパティ

### `HeaderNavItem`

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `label` | string | ヘッダーに表示されるテキスト |
| `labelKey` | string（オプション） | 翻訳が利用可能な場合に`label`をオーバーライドするi18n翻訳キー |
| `path` | string | リンク先のURLパス |
| `categoryMatch` | string（オプション） | このヘッダータブをサイドバーカテゴリにリンク |
| `versioned` | boolean（オプション） | このアイテムのリンクがアクティブな`/v/{version}`プレフィックスを持つかどうか。デフォルトは`true` |
| `children` | `HeaderNavChildItem[]`（オプション） | ドロップダウンメニューとして表示される子ナビゲーションアイテム（1階層のみ） |

### `HeaderNavChildItem`

子アイテムは`HeaderNavItem`と同じプロパティを使用しますが、独自の`children`を持つことはできません。これにより型レベルで1階層のネストが強制されます。

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `label` | string | ドロップダウンに表示されるテキスト |
| `labelKey` | string（オプション） | i18n翻訳キー |
| `path` | string | リンク先のURLパス |
| `categoryMatch` | string（オプション） | この子を別のトップレベルサイドバーカテゴリにリンク。親カテゴリ配下のネストしたパスでは省略 |
| `versioned` | boolean（オプション） | このアイテムのリンクがアクティブな`/v/{version}`プレフィックスを持つかどうか。デフォルトは`true` |

### `labelKey`

`labelKey`プロパティはヘッダーナビゲーションラベルのローカライズを可能にします。設定すると、zudo-docは現在のロケールの翻訳ファイルでキーを検索し、翻訳された文字列を`label`の代わりに使用します。翻訳が見つからない場合は`label`がフォールバックとして使用されます。

翻訳キーは`nav.*`名前空間規約に従います（例：`"nav.gettingStarted"`、`"nav.guides"`）。

### `categoryMatch`

`categoryMatch`プロパティはヘッダータブを特定のサイドバーカテゴリに接続します。`categoryMatch`を持つヘッダータブがアクティブな場合、サイドバーはそのカテゴリ内のページのみを表示するようにフィルタリングされます。

例えば、`categoryMatch: "guides"`はタブを`guides/`コンテンツディレクトリにリンクします。ユーザーが`/docs/guides/`配下のページに移動すると、「Guides」タブがアクティブになり、サイドバーにはguidesカテゴリのみが表示されます。

[ノートトレイ](https://zudo-doc.takazudomodular.com/ja/docs/guides/note-tray)は特別なヘッダーナビ型ではありません。他のトップレベルカテゴリと同じように追加し、アイテムの`path`をトレイのindexへ、単一セグメントの`categoryMatch`をトレイのディレクトリ名へ設定します。サイドバーと一覧の動作は`index.mdx`内のトレイ宣言が制御します。

子アイテムにも`categoryMatch`を設定できます。例えば、子に`categoryMatch: "components"`を設定すると、`/docs/components/`にアクセスした際に親ドロップダウンがアクティブになり、サイドバーがコンポーネントセクションにフィルタリングされます。

#### 1つのカテゴリ配下にネストした子を置く

すべての子が1つのトップレベルカテゴリ配下にネストしている場合、`categoryMatch`は親だけに設定します。子のアクティブ状態はそれぞれの`path`から判定され、親の単一セグメントの`categoryMatch`によってサイドバーにはトップレベルカテゴリ全体が表示されます。パッケージごとの変更履歴が典型的な例です：

```ts
{
  label: "Changelog",
  path: "/docs/changelog",
  categoryMatch: "changelog",
  children: [
    { label: "Core", path: "/docs/changelog/core" },
    { label: "CLI", path: "/docs/changelog/cli" },
  ],
}
```

[Dynamic content unavailable in text export]

このような子に親の`categoryMatch`をコピーしたり、`categoryMatch: "changelog/core"`のような複数セグメントの値を使用したりしないでください。`categoryMatch`はトップレベルディレクトリだけに一致するため、複数セグメントの子の値は一致せず、サイドバーが空になることがあります。2つ以上の子が同じ`categoryMatch`を共有する場合と、親または子が複数セグメントの値を使用する場合は、ビルド時に警告されます。



### `versioned`

`versioned`プロパティは、最新以外のバージョンがアクティブなときに、アイテムのリンクがアクティブな`/v/{version}`プレフィックスを持つかどうかを制御します。デフォルトは`true`です — ほとんどのヘッダーアイテムは、アーカイブされた各バージョンに対応するページを持つドキュメントコンテンツにリンクしているため、そのリンクも閲覧者と一緒にバージョンを切り替えるべきだからです。

バージョン非対応のコンテンツ（最新のドキュメントセットにのみ存在し、アーカイブされたバージョンディレクトリ内には再生成されないページ）を指すアイテムには`versioned: false`を設定してください。`versioned: false`を設定しないと、古いバージョンがアクティブなときにそのアイテムのリンクは404になります。

[Dynamic content unavailable in text export]

プロジェクトで[バージョニング](https://zudo-doc.takazudomodular.com/ja/docs/guides/versioning)を有効にしている場合は、バージョン非対応のコンテンツにリンクするすべての`headerNav`アイテムを確認し、`versioned: false`を設定してください。ショーケース自身の「Claude」と「Codex」のヘッダーアイテム（`claudeResources`機能と`codexResources`機能によるもの）が典型的な例です。これらのルートはデフォルトの`docsDir`にのみ生成され、アーカイブされたバージョンディレクトリ内には存在しないため、どちらにも`versioned: false`が設定されています。



## ドロップダウンの動作

`children`を持つアイテムはドロップダウンメニューとして表示されます。親アイテム自体は引き続きクリック可能なリンクとして機能し、クリックすると`path`に遷移します。ドロップダウンは関連するサブページへのクイックアクセスを提供します。

- **デスクトップ**：ホバーで開き、マウスがメニュー領域から離れると閉じます。小さなシェブロンがドロップダウンを示します。
- **キーボード**：トリガーがフォーカスを受けた時に開きます（`focus-within`経由）。Escapeキーで閉じます。マウスなしでも完全にアクセス可能です。
- **モバイル**：ネストアイテムはモバイルサイドバーメニューで展開可能なグループとして表示され、シェブロンをタップして子を展開/折りたたみできます。
- **オーバーフロー**：ブラウザウィンドウが狭くドロップダウンの親がオーバーフロー「...」メニューに移動された場合、子アイテムはインデントされたサブアイテムとして表示されます。

## アクティブ状態

現在のページURLがアイテムの`path`で始まる場合、そのヘッダーナビゲーションアイテムがアクティブとみなされます。現在のページが子アイテムの`path`にマッチする場合、親アイテムもアクティブとして表示されます。

例えば、`/docs/components/admonitions`にアクセスすると、`/docs/components`が子アイテムの一つにマッチするため「Learn」ドロップダウンがアクティブになります。

## モバイル動作

小さな画面（`< 1024px`）では、デスクトップヘッダーナビゲーションは非表示になります。モバイルではサイドバートグルですべてのナビゲーションにアクセスできます。ネストナビゲーションアイテムはモバイルサイドバーで展開可能なグループとして表示されます。シェブロンをタップして子を展開/折りたたみできます。