ヘッダーナビゲーション
ドロップダウンメニュー対応のヘッダーナビゲーションタブの設定
zudo-docはDocusaurusにインスパイアされたナビゲーション階層をサポートしています：
ヘッダーナビゲーション — サイトヘッダーのトップレベルタブ。オプションでドロップダウンメニューを含む
サイドバーカテゴリ — サイドバーの折りたたみ可能なグループ
サイドバーアイテム — カテゴリ内の個別ページ
Info
このページは左側のタブについて説明しています。右側クラスタ(テーマ切替・GitHub リンクなど)の設定は別ページ ヘッダー右側アイテム を参照してください。
設定
zfb.config.tsでヘッダーナビゲーションアイテムを定義します。アイテムはフラットリンクまたはネストされた子を持つドロップダウン親のいずれかです：
export default defineConfig(
zudoDoc({
// ...
headerNav: [
// フラットリンク（ドロップダウンなし）
{ label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },
// 子を持つドロップダウン親
{
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（オプション） | このアイテムのリンクがアクティブな/プレフィックスを持つかどうか。デフォルトはtrue |
children | HeaderNavChildItem[]（オプション） | ドロップダウンメニューとして表示される子ナビゲーションアイテム（1階層のみ） |
HeaderNavChildItem
子アイテムはHeaderNavItemと同じプロパティを使用しますが、独自のchildrenを持つことはできません。これにより型レベルで1階層のネストが強制されます。
| プロパティ | 型 | 説明 |
|---|---|---|
label | string | ドロップダウンに表示されるテキスト |
labelKey | string（オプション） | i18n翻訳キー |
path | string | リンク先のURLパス |
categoryMatch | string（オプション） | この子アイテムをサイドバーカテゴリにリンク |
versioned | boolean（オプション） | このアイテムのリンクがアクティブな/プレフィックスを持つかどうか。デフォルトはtrue |
labelKey
labelKeyプロパティはヘッダーナビゲーションラベルのローカライズを可能にします。設定すると、zudo-docは現在のロケールの翻訳ファイルでキーを検索し、翻訳された文字列をlabelの代わりに使用します。翻訳が見つからない場合はlabelがフォールバックとして使用されます。
翻訳キーはnav.*名前空間規約に従います（例："nav.gettingStarted"、"nav.guides"）。
categoryMatch
categoryMatchプロパティはヘッダータブを特定のサイドバーカテゴリに接続します。categoryMatchを持つヘッダータブがアクティブな場合、サイドバーはそのカテゴリ内のページのみを表示するようにフィルタリングされます。
例えば、categoryMatch: "guides"はタブをguides/コンテンツディレクトリにリンクします。ユーザーが/配下のページに移動すると、「Guides」タブがアクティブになり、サイドバーにはguidesカテゴリのみが表示されます。
子アイテムにもcategoryMatchを設定できます。例えば、子にcategoryMatch: "components"を設定すると、/にアクセスした際に親ドロップダウンがアクティブになり、サイドバーがコンポーネントセクションにフィルタリングされます。
versioned
versionedプロパティは、最新以外のバージョンがアクティブなときに、アイテムのリンクがアクティブな/プレフィックスを持つかどうかを制御します。デフォルトはtrueです — ほとんどのヘッダーアイテムは、アーカイブされた各バージョンに対応するページを持つドキュメントコンテンツにリンクしているため、そのリンクも閲覧者と一緒にバージョンを切り替えるべきだからです。
バージョン非対応のコンテンツ（最新のドキュメントセットにのみ存在し、アーカイブされたバージョンディレクトリ内には再生成されないページ）を指すアイテムにはversioned: falseを設定してください。versioned: falseを設定しないと、古いバージョンがアクティブなときにそのアイテムのリンクは404になります。
Warning
プロジェクトでバージョニングを有効にしている場合は、バージョン非対応のコンテンツにリンクするすべてのheaderNavアイテムを確認し、versioned: falseを設定してください。ショーケース自身の「Claude」ヘッダーアイテム（claudeResources機能によるもの）が典型的な例です。これらのルートはデフォルトのdocsDirにのみ生成され、アーカイブされたバージョンディレクトリ内には存在しないため、versioned: falseが設定されています。
ドロップダウンの動作
childrenを持つアイテムはドロップダウンメニューとして表示されます。親アイテム自体は引き続きクリック可能なリンクとして機能し、クリックするとpathに遷移します。ドロップダウンは関連するサブページへのクイックアクセスを提供します。
デスクトップ：ホバーで開き、マウスがメニュー領域から離れると閉じます。小さなシェブロンがドロップダウンを示します。
キーボード：トリガーがフォーカスを受けた時に開きます（
focus-within経由）。Escapeキーで閉じます。マウスなしでも完全にアクセス可能です。モバイル：ネストアイテムはモバイルサイドバーメニューで展開可能なグループとして表示され、シェブロンをタップして子を展開/折りたたみできます。
オーバーフロー：ブラウザウィンドウが狭くドロップダウンの親がオーバーフロー「...」メニューに移動された場合、子アイテムはインデントされたサブアイテムとして表示されます。
アクティブ状態
現在のページURLがアイテムのpathで始まる場合、そのヘッダーナビゲーションアイテムがアクティブとみなされます。現在のページが子アイテムのpathにマッチする場合、親アイテムもアクティブとして表示されます。
例えば、/にアクセスすると、/が子アイテムの一つにマッチするため「Learn」ドロップダウンがアクティブになります。
モバイル動作
小さな画面（< 1024px）では、デスクトップヘッダーナビゲーションは非表示になります。モバイルではサイドバートグルですべてのナビゲーションにアクセスできます。ネストナビゲーションアイテムはモバイルサイドバーで展開可能なグループとして表示されます。シェブロンをタップして子を展開/折りたたみできます。