CategoryNav
A server-rendered Preact component that renders a grid of child page cards for category index pages.
Overview
CategoryNav is a server-rendered Preact 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.
Info
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:
Usage
Use CategoryNav in a category's index.mdx to create a landing page:
---
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:
<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.
Features
2-column grid — displays
sm:grid-cols-2on desktop, single column on mobileCard 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_positionordering 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/Source
The component is defined at pages/.