## 概要

`CategoryNav`は、カテゴリの子ページをカードグリッドとして自動的に一覧表示する、サーバーレンダリングのzudo-reactコンポーネントです。カテゴリの`index.mdx`ファイルで使用し、すべての子ページへのリンクを含むランディングページを作成するために設計されています。

フラットで順序付きのノートトレイには、代わりに[`NoteTrayIndex`](https://zudo-doc.takazudomodular.com/ja/docs/components/note-tray-index)を使用してください。トレイのrank、日付、設定された昇順・降順を保ち、index、card、timelineの3つの表示形式を選べます。

[Dynamic content unavailable in text export]

`CategoryNav`はすべてのMDXドキュメントページでグローバルに利用できます — インポートは不要です。アドモニションコンポーネント（`Note`、`Tip`など）と同様に、ドキュメントページルートで登録されています。



## ライブデモ

以下は`CategoryNav`で「はじめに」カテゴリを表示した例です：

[Dynamic content unavailable in text export]

## 使い方

カテゴリの`index.mdx`で`CategoryNav`を使用してランディングページを作成します：

```mdx
---
title: Getting Started
sidebar_position: 0
---

Welcome to the Getting Started section. Choose a topic below to begin.

<CategoryNav category="getting-started" />
```

`CategoryNav`は完全にサーバー側でレンダリングされ、クライアントサイドJavaScriptはゼロです — ハイドレートディレクティブは不要です。

## プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `category` | `string` | — | 直下の子ページを一覧表示するカテゴリスラッグ（例：`"guides"`、`"reference"`） |
| `categories` | `string[]` | — | カードとして表示するカテゴリスラッグの明示的なリスト。対象が共通の親の子ではなく、ナビゲーションツリー上の兄弟関係にある場合に使用 |
| `lang` | `Locale` | 自動検出 | コンテンツコレクションのロケールを上書き |

`category`または`categories`のいずれかを指定します。両方を指定した場合は`categories`が優先され、`category`は無視されます。どちらも指定しない場合は、コンポーネントは何も表示しません。

`lang`プロップは現在のURLパスから自動的に検出されるため、通常は設定する必要はありません。

### `categories`プロップ

デフォルトでは、`CategoryNav`は単一の親を推測し、その直下の子を一覧表示します。対象が1つの共通の親の子ではなく、ナビゲーションツリー上の最上位の兄弟である場合は、代わりに`categories`を渡します。たとえば`claude-md`と`claude-skills`は`claude`の子ではなく、`claude`と同じ最上位の階層に並ぶ兄弟です：

```mdx
<CategoryNav categories={["claude-md", "claude-skills", "claude-agents"]} />
```

各スラッグは対応するナビゲーションノードに解決され、カードとして表示されます。ツリー内で見つからないスラッグは、エラーにならず単に無視されます。no-pageカテゴリ（`index.mdx` の `category_no_page: true`、またはレガシーの `_category_.json` の `noPage: true`）はそれ自体のルートを持たないため、カードのリンク先はそのカテゴリ配下で最初にルートを持つ子ページになります。到達可能なページがない no-page カテゴリは、リンク切れを出力する代わりにスキップされます。

### ネストしたカテゴリ

`category`プロップには、ネストしたカテゴリパスも指定できます。例えば、`<CategoryNav category="changelog/core" />`は`guides/layout-demos`と同じパターンで、`changelog/core/`直下のリリースページを一覧表示します。親のランディングページでは、`<CategoryNav category="changelog" />`によって各パッケージサブカテゴリの`index.mdx`が1枚ずつカードとして表示されます。

## 特徴

- **2カラムグリッド** — デスクトップでは`sm:grid-cols-2`、モバイルではシングルカラムで表示
- **カード表示** — 各カードにはページタイトル（リンク付き）とdescription（frontmatterから取得）を表示
- **ホバーエフェクト** — ホバー時にカードのボーダーがハイライトされ、タイトルリンクは常に下線付き
- **インデックス自動除外** — カテゴリ自身のインデックスページは自動的にフィルタリング
- **ポジション順ソート** — カードはfrontmatterの`sidebar_position`順に並びます

## 使用場所

任意のカテゴリの`index.mdx`に`CategoryNav`を追加してランディングページを生成できます。例えば、「はじめに」セクションでは以下のように使用されています：

```
src/content/docs/
  getting-started/
    index.mdx              ← uses <CategoryNav category="getting-started" />
    introduction.mdx
    installation.mdx
    writing-docs.mdx
```

## ソース

コンポーネントのレンダリングロジックはパッケージの`@takazudo/zudo-doc/category-nav`から提供され、パッケージ所有ルート（`packageOwnedRoutes`、デフォルトで有効）を通じてすべてのMDXドキュメントページに自動的に組み込まれます — プロジェクト側で保守すべきファイルはありません。