## 概要

zudo-doc は **3 階層のナビゲーション構造** でコンテンツを整理します。

1. **ヘッダーナビゲーション** — サイト全体に表示される、最も広い最上位カテゴリ
2. **サイドバー** — 各ヘッダーナビセクション内の次のレベルの分類
3. **サイドバーのネストカテゴリ** — サイドバーセクション内の詳細なサブカテゴリ

各レベルはスコープを絞り込みます。ヘッダーはサイトの全体像を示し、サイドバーはセクションを論理的なグループに分け、ネストカテゴリは必要に応じて細かい構造を追加します。

## ファイル構造 = ナビゲーション構造

[Dynamic content unavailable in text export]

zudo-doc では、**ファイルとディレクトリの構造がそのままナビゲーションになります**。別途ナビゲーション設定を管理する必要はありません。サイドバーは `src/content/docs/` のディレクトリツリーから自動生成され、ヘッダーナビの各項目は `categoryMatch` でトップレベルディレクトリに対応します。

つまり、ファイルツリーを見るだけでサイト全体のナビゲーションを把握できます。リポジトリを読む人間にとっても、コンテンツを生成する AI ツールにとっても、同じように直感的です。



**ファイル構造とナビゲーション構造を密に結合させてください。** サイドバーカテゴリ「Hardware」が必要なら `hardware/` ディレクトリを作成します。ヘッダーナビに「Guides」の項目が必要なら `guides/` ディレクトリを作成し `categoryMatch: "guides"` を設定します。ディレクトリ名、URL パス、ナビゲーションのラベルはすべて対応させるのが理想です。

この密結合が推奨される理由は以下の通りです。

- **予測可能性** — ファイルの配置場所を見れば、ナビゲーションのどこに表示されるかが常にわかる
- **乖離がない** — 実際のコンテンツと同期がずれる別の設定ファイルが存在しない
- **AI フレンドリー** — AI ツールがディレクトリ構造の規約に従うだけで、正確なナビゲーションを生成できる

zudo-doc は複雑なケースに対応する高度な設定（カスタムサイドバーラベル、ソート順の上書き、ネストドロップダウンなど）もサポートしていますが、デフォルトの動作 — ディレクトリがカテゴリに、ファイルがページになる — でほとんどのケースに対応できます。まずはシンプルに始めて、デフォルトの対応では不十分な場合にのみ複雑さを追加してください。

### ホームのナビゲーショングリッドを広げる

ホームページは同じコンテンツツリーをカテゴリグリッドとして表示します。
デフォルトでは標準のサイドバーなしコンテンツ幅を使います。大きな
ナビゲーションツリーでは、`zfb.config.ts` からビューポート指向の広い
グリッドを有効にできます。

```ts
zudoDoc({
  home: { wide: true },
});
```

この設定はデフォルトロケールのホームページと、すべてのロケール接頭辞付き
ホームページを広げます。スキャフォールドされた `pages/index.tsx` の
再エクスポートを置き換えたり、ロケール用ホームルートを別途書いたりする
必要はありません。設定の完全な契約は[設定](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%83%9B%E3%83%BC%E3%83%A0%E3%83%9A%E3%83%BC%E3%82%B8-home)
を参照してください。

### ホームグリッドからカテゴリを非表示にする

```ts
zudoDoc({
  siteTreeNavIgnore: ["inbox", "develop"],
});
```

この設定はこれらのトップレベルカテゴリを `/`、ロケールのホームページ、`<SiteTreeNav />` から非表示にします。ヘッダーナビ、サイドバー、検索、サイトマップに影響しない完全な契約は[設定](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%83%9B%E3%83%BC%E3%83%A0%E3%83%9A%E3%83%BC%E3%82%B8-sitetreenavignore)を参照してください。

### カテゴリをセカンダリ行へ移す

```ts
zudoDoc({
  siteTreeNavSecondary: ["changelog", "claude", "codex"],
});
```

すべてのトップレベルカテゴリが、主要な読み進めの導線になるわけではありません。長い変更履歴や、自動生成される Claude・Codex のリソース一覧のようなシステム系のカテゴリは、読者が読み始めの起点にすることの少ない大きなカードでホームグリッドを埋めてしまいます。このショーケースではこれらを `siteTreeNavSecondary` に指定しています。指定したカテゴリはグリッドから外れ、その直下にシェブロン付きリンクのコンパクトな行として、配列の順に表示されます。`/` からワンクリックで辿れる状態を保ちながら、グリッドはガイド類に集中させられます。

スラッグが `siteTreeNavIgnore` にも含まれる場合、そのカテゴリは代わりに非表示になります。また、MDX の `<SiteTreeNav />` タグはこの設定を無視します。設定の完全な契約は[設定](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%83%9B%E3%83%BC%E3%83%A0%E3%83%9A%E3%83%BC%E3%82%B8-sitetreenavsecondary)を参照してください。

## ヘッダーナビゲーションのルール

ヘッダーナビゲーションは最上位のレベルです。サイトの主要セクションを定義する、最も広いカテゴリのみを含めてください。

- **簡潔にする** — 3〜6 項目を目安にしましょう。それ以上はユーザーを圧倒し、ヘッダーが煩雑になります。
- **ドロップダウンは控えめに** — 密接に関連するセクションをまとめる場合のみ使用します（例：「学習」に「ガイド」と「コンポーネント」を含める）。
- **各項目はコンテンツディレクトリに対応** — 設定の `categoryMatch` フィールドがヘッダー項目をそのセクションのサイドバーコンテンツにリンクします。

[Dynamic content unavailable in text export]

設定の詳細は [ヘッダーナビゲーション](https://zudo-doc.takazudomodular.com/ja/docs/guides/header-navigation) を参照してください。



### ヘッダー設定の例

ヘッダーナビゲーションは、`zfb.config.ts` 内の唯一の `zudoDoc()` 設定の `headerNav` フィールドです:

```ts
// zfb.config.ts
export default defineConfig(
  zudoDoc({
    headerNav: [
      { label: "Getting Started", path: "/docs/getting-started", categoryMatch: "getting-started" },
      {
        label: "Learn",
        path: "/docs/guides",
        categoryMatch: "guides",
        children: [
          { label: "Guides", path: "/docs/guides", categoryMatch: "guides" },
          { label: "Components", path: "/docs/components", categoryMatch: "components" },
        ],
      },
      { label: "Reference", path: "/docs/reference", categoryMatch: "reference" },
    ],
  }),
);
```

## サイドバー構造のルール

サイドバーは、各ヘッダーナビセクション内の次のレベルの分類を提供します。ディレクトリ構造から自動的に生成されます。

- **カテゴリにはディレクトリを使う** — 各ディレクトリが折りたたみ可能なサイドバーグループになります。
- **各カテゴリディレクトリに `index.mdx` を用意する** — カテゴリのランディングページとして機能し、`sidebar_position` を設定します。
- **ネストは 2〜3 レベルまで** — 深いネストはナビゲーションしづらく、コンテンツの再編成が必要なサインです。
- **すべてのページに `sidebar_position` を設定する** — アルファベット順のデフォルトに頼らず、予測可能な順序を確保します。

[Dynamic content unavailable in text export]

設定の詳細は [サイドバー](https://zudo-doc.takazudomodular.com/ja/docs/guides/sidebar) を参照してください。



### ディレクトリからサイドバーへのマッピング

```
src/content/docs/guides/        ← サイドバーカテゴリ「Guides」
├── index.mdx                   ← カテゴリランディング（sidebar_position: 0）
├── configuration.mdx           ← sidebar_position: 1
├── sidebar.mdx                 ← sidebar_position: 2
└── header-navigation.mdx       ← sidebar_position: 3
```

各 `.mdx` ファイルがサイドバー項目として表示されます。サブディレクトリはネストされた折りたたみ可能なカテゴリになります。

### カテゴリの形

多くのカテゴリはツリーです。サブディレクトリを含めることができ、`index.mdx`は`<CategoryNav>`を置いた短いランディングページになります。これに対して**ノートトレイ**は、日誌、講座、ノート集のようなトップレベルのフラットなページ列に使います。`index.mdx`で`category_shape: "note-tray"`を宣言し、すべてのアイテムをカテゴリ直下に置き、ランディングページの一覧には`<NoteTrayIndex>`を使います。日付を全アイテムに設定すれば、年または月でグループ化することもできます。

このショーケースの「はじめに」はノートトレイです。ページ群はネストしたトピックツリーではなく、意図した1本の読み順を構成します。宣言と検証の詳しい仕様は[ノートトレイ](https://zudo-doc.takazudomodular.com/ja/docs/guides/note-tray)を参照してください。

### カテゴリトップページ（index.mdx）

各カテゴリディレクトリには、そのカテゴリの**ランディングページ**となる`index.mdx`を用意してください。通常のツリーカテゴリでは内容をシンプルに保ち、カテゴリの説明を1〜2文で書いた後に、兄弟ページへのリンクを自動表示する`<CategoryNav>`を置きます。ノートトレイでは代わりに`<NoteTrayIndex>`を使います。

```mdx
---
title: Guides
sidebar_position: 1
---

Step-by-step guides for common zudo-doc tasks.

<CategoryNav category="guides" />
```

`category`プロパティにはトップレベルのディレクトリ名を指定します（例：`src/content/docs/guides/`なら`"guides"`）。indexにドキュメントの本文を書かないでください。実際のドキュメントは同じディレクトリ内の兄弟`.mdx`ファイルに置きましょう。使用する一覧コンポーネントは異なっても、ノートトレイのindexも同じように簡潔に保ちます。

## 具体的な実例

**ゲーム攻略 Wiki** を構築する場合のナビゲーション構造です。

### ナビゲーション計画

```
ヘッダーナビ:
├── ホーム
├── プラットフォーム        ← ドロップダウン
│   ├── Xbox
│   ├── PlayStation
│   └── Nintendo
├── ジャンル                ← ドロップダウン
│   ├── RPG
│   ├── アクション
│   └── ストラテジー
└── コミュニティ
```

ユーザーが「プラットフォーム」ドロップダウンで「Xbox」をクリックすると、サイドバーは以下のように表示されます。

```
サイドバー（Xbox セクション）:
├── 概要（index）
├── ハードウェア
│   ├── Xbox Series X
│   ├── Xbox Series S
│   └── アクセサリ
├── ゲーム
│   ├── Halo Infinite
│   ├── Forza Horizon 5
│   └── Starfield
└── サービス
    ├── Game Pass
    └── Xbox Live
```

### ゲーム Wiki のヘッダー設定

`categoryMatch` の値は **単一のトップレベルディレクトリ名** である必要があります。フレームワークは現在の URL の最初のパスセグメントのみを照合してアクティブ状態を解決します。

```ts
// zfb.config.ts
export default defineConfig(
  zudoDoc({
    headerNav: [
      { label: "Home", path: "/docs/home", categoryMatch: "home" },
      {
        label: "Platforms",
        path: "/docs/xbox",
        categoryMatch: "xbox",
        children: [
          { label: "Xbox", path: "/docs/xbox", categoryMatch: "xbox" },
          { label: "PlayStation", path: "/docs/playstation", categoryMatch: "playstation" },
          { label: "Nintendo", path: "/docs/nintendo", categoryMatch: "nintendo" },
        ],
      },
      {
        label: "Genres",
        path: "/docs/rpg",
        categoryMatch: "rpg",
        children: [
          { label: "RPG", path: "/docs/rpg", categoryMatch: "rpg" },
          { label: "Action", path: "/docs/action", categoryMatch: "action" },
          { label: "Strategy", path: "/docs/strategy", categoryMatch: "strategy" },
        ],
      },
      { label: "Community", path: "/docs/community", categoryMatch: "community" },
    ],
  }),
);
```

### ゲーム Wiki のディレクトリ構造

各プラットフォームとジャンルが独自のトップレベルディレクトリを持つことで、`categoryMatch` が URL の最初のセグメントと正しく対応します。

```
src/content/docs/
├── home/
│   └── index.mdx
├── xbox/
│   ├── index.mdx                  ← 「概要」
│   ├── hardware/
│   │   ├── index.mdx
│   │   ├── xbox-series-x.mdx
│   │   ├── xbox-series-s.mdx
│   │   └── accessories.mdx
│   ├── games/
│   │   ├── index.mdx
│   │   ├── halo-infinite.mdx
│   │   ├── forza-horizon-5.mdx
│   │   └── starfield.mdx
│   └── services/
│       ├── index.mdx
│       ├── game-pass.mdx
│       └── xbox-live.mdx
├── playstation/
│   └── index.mdx
├── nintendo/
│   └── index.mdx
├── rpg/
│   └── ...
├── action/
│   └── ...
├── strategy/
│   └── ...
└── community/
    └── index.mdx
```

## よくある間違い

[Dynamic content unavailable in text export]

ナビゲーション設定で避けるべき落とし穴です。

- **ヘッダーに詰め込みすぎる** — ヘッダーには広いカテゴリだけを置きましょう。10 個以上の項目がある場合、ほとんどはサイドバーに属します。
- **深すぎるサイドバーのネスト** — 3 レベル以上のネストはコンテンツを見つけにくくします。別のヘッダーナビセクションに分割してフラットにしましょう。
- **無関係なトピックの混在** — 各サイドバーセクションは一貫したエリアをカバーするべきです。「ハードウェア」と「コミュニティイベント」が同じサイドバーにある場合は、ヘッダーカテゴリを見直しましょう。
- **`sidebar_position` の未設定** — 設定しないとページがアルファベット順にソートされ、混乱を招くことが多いです。予測可能なナビゲーションのために必ず `sidebar_position` を設定しましょう。
- **カテゴリディレクトリに `index.mdx` がない** — index がないとカテゴリにランディングページがなく、サイドバーに正しく表示されない場合があります。
- **`categoryMatch` に複数セグメントの値を使う**（例：`"platforms/xbox"`）— `categoryMatch` は単一のトップレベルディレクトリ名でなければなりません。複数セグメントの値はヘッダーナビのアクティブ状態ハイライトを壊します。



## AI ツールによるセットアップのヒント

AI ツールで zudo-doc のサイト構造を生成する際は、以下のルールに従って一貫した結果を得てください。

- **階層構造を厳密に守る** — ヘッダーナビは広いカテゴリ、サイドバーはサブカテゴリ、ネストディレクトリはさらなる詳細。レベルを飛ばさないでください。
- **ヘッダーナビには広いカテゴリのみ** — 個別のページをヘッダーに追加したくなる誘惑に負けないでください。それはサイドバーの役割です。
- **`categoryMatch` の値を実際のディレクトリ名と一致させる** — `categoryMatch: "guides"` は `src/content/docs/guides/` ディレクトリに対応する必要があります。
- **すべてのカテゴリディレクトリに `index.mdx` を必ず作成する** — カテゴリに適切なランディングページとサイドバーエントリを確保します。
- **すべてのページとインデックスに `sidebar_position` を設定する** — AI ツールが最も忘れやすいポイントで、予測不可能な順序につながります。
- **ディレクトリとファイル名にケバブケースを使う** — 一貫した命名でプラットフォーム間の大文字小文字の問題を回避します。