ナビゲーション構造の設計

ヘッダーナビゲーションとサイドバーカテゴリの整理方法

概要

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

1. ヘッダーナビゲーション — サイト全体に表示される、最も広い最上位カテゴリ

2. サイドバー — 各ヘッダーナビセクション内の次のレベルの分類

3. サイドバーのネストカテゴリ — サイドバーセクション内の詳細なサブカテゴリ

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

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

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

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

• 予測可能性 — ファイルの配置場所を見れば、ナビゲーションのどこに表示されるかが常にわかる

• 乖離がない — 実際のコンテンツと同期がずれる別の設定ファイルが存在しない

• AI フレンドリー — AI ツールがディレクトリ構造の規約に従うだけで、正確なナビゲーションを生成できる

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

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

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

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

この設定はデフォルトロケールのホームページと、すべてのロケール接頭辞付き ホームページを広げます。スキャフォールドされた pages/index.tsx の 再エクスポートを置き換えたり、ロケール用ホームルートを別途書いたりする 必要はありません。設定の完全な契約は設定 を参照してください。

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

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

• 簡潔にする — 3〜6 項目を目安にしましょう。それ以上はユーザーを圧倒し、ヘッダーが煩雑になります。

• ドロップダウンは控えめに — 密接に関連するセクションをまとめる場合のみ使用します（例：「学習」に「ガイド」と「コンポーネント」を含める）。

• 各項目はコンテンツディレクトリに対応 — 設定の categoryMatch フィールドがヘッダー項目をそのセクションのサイドバーコンテンツにリンクします。

ヘッダー設定の例

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

// 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 を設定する — アルファベット順のデフォルトに頼らず、予測可能な順序を確保します。

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

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）

各カテゴリディレクトリには、そのカテゴリのランディングページとなる index.mdx を用意してください。内容はシンプルに保ちます。カテゴリの説明を 1〜2 文で書き、その後に <CategoryNav> コンポーネントを置くだけです。このコンポーネントは兄弟ページへのリンクを自動的に表示します。

---
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 ファイルに置きましょう。

具体的な実例

ゲーム攻略 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 の最初のパスセグメントのみを照合してアクティブ状態を解決します。

// 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

よくある間違い

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

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

• 階層構造を厳密に守る — ヘッダーナビは広いカテゴリ、サイドバーはサブカテゴリ、ネストディレクトリはさらなる詳細。レベルを飛ばさないでください。

• ヘッダーナビには広いカテゴリのみ — 個別のページをヘッダーに追加したくなる誘惑に負けないでください。それはサイドバーの役割です。

• categoryMatch の値を実際のディレクトリ名と一致させる — categoryMatch: "guides" は src/content/docs/guides/ ディレクトリに対応する必要があります。

• すべてのカテゴリディレクトリに index.mdx を必ず作成する — カテゴリに適切なランディングページとサイドバーエントリを確保します。

• すべてのページとインデックスに sidebar_position を設定する — AI ツールが最も忘れやすいポイントで、予測不可能な順序につながります。

• ディレクトリとファイル名にケバブケースを使う — 一貫した命名でプラットフォーム間の大文字小文字の問題を回避します。