## Overview

`CategoryNav` is a server-rendered zudo-react component that automatically lists child pages of a category as a card grid. It is designed for use in category `index.mdx` files to create landing pages that link to all child pages.

For a flat, ordered note tray, use [`NoteTrayIndex`](https://zudo-doc.takazudomodular.com/docs/components/note-tray-index) instead. It preserves tray ranks, dates, and the configured ascending or descending order, and offers index, card, and timeline presentations.

[Dynamic content unavailable in text export]

`CategoryNav` is globally available in all MDX doc pages — no import needed. It is registered alongside the admonition components (`Note`, `Tip`, etc.) in the doc page route.



## Live Example

Here is `CategoryNav` rendering the Getting Started category:

[Dynamic content unavailable in text export]

## Usage

Use `CategoryNav` in a category's `index.mdx` to create a landing page:

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

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

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

`CategoryNav` renders entirely on the server with zero client-side JavaScript — no hydration directive is needed.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `category` | `string` | — | The category slug whose immediate children are listed (e.g., `"guides"`, `"reference"`) |
| `categories` | `string[]` | — | Explicit list of category slugs to render as cards. Use when the targets are siblings in the nav tree rather than children of a common parent |
| `lang` | `Locale` | auto-detected | Override the locale for the content collection |

Provide either `category` or `categories`. When both are set, `categories` takes precedence and `category` is ignored; when neither is set, the component renders nothing.

The `lang` prop is automatically detected from the current URL path, so you typically don't need to set it.

### The `categories` prop

By default `CategoryNav` infers a single parent and lists its immediate children. Pass `categories` instead when the targets are not children of one common parent but top-level siblings in the nav tree — for example `claude-md` and `claude-skills` are top-level peers of `claude`, not nested under it:

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

Each slug is resolved to its nav node and rendered as a card; slugs not found in the tree are silently skipped. A no-page category (`category_no_page: true` in `index.mdx`, or `noPage: true` in a legacy `_category_.json`) has no route of its own, so its card links to the category's first routed descendant page; a no-page category with no reachable page is skipped rather than rendering a dead link.

### Nested categories

The `category` prop also accepts a nested category path. For example, `<CategoryNav category="changelog/core" />` lists the immediate release pages under `changelog/core/`, following the same pattern as `guides/layout-demos`. On the parent landing page, `<CategoryNav category="changelog" />` renders one card for each package subcategory's `index.mdx`.

## Features

- **2-column grid** — displays `sm:grid-cols-2` on desktop, single column on mobile
- **Card display** — each card shows the page title (as a link) and description (from frontmatter)
- **Hover effect** — card border highlights on hover; the title link is always underlined
- **Auto-excludes index** — the category's own index page is automatically filtered out
- **Sorted by position** — cards follow `sidebar_position` ordering from frontmatter

## Where to Use

Add `CategoryNav` to any category's `index.mdx` to generate a landing page. For example, the Getting Started section uses it:

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

## Source

The component's rendering logic ships from the package at `@takazudo/zudo-doc/category-nav`, and is wired into every MDX doc page automatically via the package-owned routes (`packageOwnedRoutes`, on by default) — there is no project file to maintain.