| Field | Value |
| --- | --- |
| `user-invocable` | `true` |

# zudo-doc Navigation Design Rules

**IMPORTANT**: Consult these rules before creating new doc pages, adding categories, or designing the site's navigation. AI tools tend to pattern-match to personal preference and produce chaotic structures; this skill encodes the correct approach.

## Reference Documentation

This skill is the short version. The authoritative guides are:

- `src/content/docs/getting-started/structuring-navigations.mdx` — choosing a pattern (decision table) and the gaming-wiki walkthrough.
- `src/content/docs/guides/sidebar.mdx` — category rows, sidebar item semantics, `initialPath`/`initialPathMode`, `scopeRoot`, and scope recipes.
- `src/content/docs/guides/editorial-navigation.mdx` — the advanced recipes for re-parenting existing pages without moving their URLs: a curated editorial tree, and an umbrella tree that keeps complete sections under one linked landing page.
- `src/content/docs/guides/maintaining-documentation-structure.mdx` — the placement check, when a structure review is warranted, how to compare keeping versus reorganizing, and how a project records its editorial policy.

Link to those guides instead of copying their advanced implementation into another file.

## Placement Check Before Adding or Re-scoping Content

Typo, wording, and formatting fixes need no placement check. When a change adds a page, adds a new reader task or topic, or changes a page's role, answer four questions first:

1. Who can do what with this content?
2. Does an existing page already serve that role? (Prefer updating it.)
3. Why this category, and is there a competing destination?
4. Does this addition change what the category means?

Clear answers → place the page and report the reason in one line. Evidence of a category conflict, duplication, a new independent cluster of reader tasks, or a findability problem → structure review: write the concrete reader problem, read the category map plus only the related or competing pages (say what you surveyed), and compare adding to an existing page, improving while keeping the structure, a local reorganization, and related links or an index. Keep the options that solve the problem, then prefer the smaller change; keeping the structure is a valid outcome. Never decide by page count or balance, and do not re-reorganize a category without new evidence. Distinguish a logical reclassification from a file move (which changes the URL).

## Write the Intended Tree Before Choosing Configuration

Before you touch `headerNav`, `sidebars`, or chrome bindings, write down:

1. The complete parent/child tree the reader should see, marking each row as linked or heading-only.
2. For each destination page: which section owns it (its URL's `categoryMatch`), what a fresh visit and **Restore** show, which branches start open, and how far **Broaden tree** may go.

Then pick the pattern that produces that tree. Four patterns look alike and are not interchangeable:

- **Header dropdown** — collects independent sections in the header. It creates no sidebar parent.
- **Shared sidebar hierarchy** — one linked landing page is the real parent of the rows below it.
- **Curated editorial tree** — lists particular pages and cross-links; a cross-link stays a leaf (`guides/editorial-navigation.mdx`).
- **Umbrella tree** — a shared hierarchy whose children are complete native sections; only the section list is authored (`guides/editorial-navigation.mdx#umbrella-tree-with-complete-sections`). This showcase's Learn sidebar is one (`src/lib/learn-navigation.ts`, `src/lib/learn-chrome.tsx`).

When asked to match an existing hierarchy, keep its linked parent rows and every descendant. Do not substitute a flat hub of peer links because the directories happen to be siblings. A list of section pages such as `items: ["learn", "guides", "components"]` is that flat hub: each string is a leaf. `scopeRoot` only caps Broaden, and `initialPath` only selects a view; neither creates ancestry.

## The 3-Level Hierarchy

Design for three levels. This is a usability recommendation, not a technical maximum — the sidebar is recursive and renders any depth — but deeper trees are harder to read:

1. **Header nav** — the biggest categories (3–6 items max)
2. **Sidebar** — all pages in the active category (generated from the filesystem)
3. **Nested sidebar categories** — subsections within a sidebar (2–3 levels of nesting max)

Each level narrows scope. Never jump levels — do not put a specific page directly in the header, and do not hide a whole category in a nested sidebar fold.

## File Structure Is the Default Navigation

**This is the single most important rule.** By default, the directory tree under `src/content/docs/` *is* the navigation, with no separate config to keep in sync. Recommend this default first.

- A directory becomes a sidebar category. Its `index.mdx` is the category landing page.
- A file becomes a sidebar item.
- Subdirectories become nested collapsible categories.
- The `headerNav` setting maps top-level directories to header items via `categoryMatch`.

## Category Shapes

Choose the category shape before writing its index:

- **Tree (default)** — a topic hierarchy that may contain subdirectories. Keep `index.mdx` to a short intro plus `<CategoryNav category="<category-path>" />`.
- **Note tray** — a top-level, flat sequence such as a journal, course, or notebook: papers on a tray, latest on top or read in order. Declare `category_shape: "note-tray"` on its visible routed `index.mdx`, allow only direct child files, and use `<NoteTrayIndex>` instead of `<CategoryNav>`.

Note trays keep the normal `sidebar_position` comparator and use `category_sort_order` everywhere. `note_tray_dated: true` requires a quoted, calendar-valid `date` on every item, including unlisted items. `note_tray_sidebar` accepts `"index"`, `"year"`, or `"month"`; year/month grouping requires a dated tray. Keep `sidebar_position` monotonic with `date` as a documented recommendation, not a validation rule.

**Consequence**: design the filesystem with navigation in mind from the start. When the wanted hierarchy differs from the directories, move the files.

Editorial trees are supported for the case where existing URLs must stay but the sidebar needs different parents, including cross-section collections. That is an advanced chrome-bindings recipe (`guides/editorial-navigation.mdx`); recommend it only when moving files is not an option.

## Linked Parents vs Heading-Only Groups

Decide for every group row whether it is a link:

- **Linked parent** — a real category node backed by a page. An authored `index.mdx` gives it intentional landing content, label, and position. Keep the real node and its native children; do not wrap it in a synthetic category and do not repeat the landing page as an "Overview" child.
- **Heading-only group** — no page of its own. Use `category_no_page: true` on the `index.mdx`, or a synthetic `{ type: "category" }` sidebar item.

A synthetic `type: "category"` never has an `href`, and `SidebarCategory` has no property that links it to a page. Putting a landing page inside one produces an unlinked heading with the landing page duplicated as its first child.

The renderer chooses linked versus heading-only by whether the row has an `href`. `hasPage` is not a navigability test: generated auto-index rows and `type: "link"` items have `hasPage: false` but still link.

## Header Navigation Rules

The header is the topmost level. It holds only the biggest categories.

- **3–6 items max.** More than 6 overwhelms users and wraps the header.
- **Each item is a broad section, not a page.** "Guides" ✓, "How to install" ✗.
- **`categoryMatch` must be a single top-level directory name.** Multi-segment values (e.g. `"platforms/xbox"`) break active-state highlighting and sidebar scoping. When dropdown children are nested under one top-level directory, keep `categoryMatch` on the parent and omit it from the children; child active state comes from `path`. Per-package changelogs (`changelog/core`, `changelog/cli`) are the canonical example. Children that represent separate top-level directories may each use their own single-segment `categoryMatch`.
- **A dropdown is header-only.** Its children stay independent sections with their own sidebars; it never makes them sidebar children. For a sidebar parent, use an umbrella tree and keep each child's own `categoryMatch`.
- **Dropdowns are for closely related sections only.** "Learn > Guides, Components" makes sense. "Everything > 7 miscellaneous items" does not — split into separate header items instead.

## Sidebar Structure Rules

The sidebar is generated from the filesystem. The rules are about how you organize files:

- **Author an `index.mdx` for every category directory.** It supplies intentional landing content and metadata; its `sidebar_position` sets the category's position. Without one, an ordinary category that contains pages still gets a generated auto-index route and a linked row, but with a default label and position. `category_no_page: true` removes the route and the link. Note trays are stricter: they require a visible routed `index.mdx`.
- **Every page MUST set `sidebar_position`.** Without it, pages sort alphabetically — which is almost never what you want. This is the single most common AI mistake.
- **Nesting depth: prefer 2–3 levels.** Deep nesting hides content. If you need more, the header nav is probably missing a category — split it out. This is a readability rule, not an enforced limit.
- **Each sidebar section should cover one cohesive topic.** Do not mix unrelated themes in the same sidebar (e.g. "Hardware" and "Community Events" under the same section).
- **Use kebab-case directory and file names.** `my-article.mdx`, not `myArticle.mdx`.
- **Recommend each major category landing page as the sidebar ceiling.** Keep its linked row and native descendants on its landing page and articles; use the header to switch major categories. Bind `{ items: [], scopeRoot: "configured" }` for each `categoryMatch`. At that root Broaden is absent. Omitted definitions retain the package's broader editorial default; this is an authoring recommendation, not a changed runtime default.
- **Narrow further only for a large or deep category with substantial nested groups.** A short, flat category should show its whole tree without a narrower `initialPath`. Branch focus can broaden back to the configured category ceiling. A whole-site sidebar is usually appropriate only for very small documentation.

## Checklist for Adding a New Page

Before creating any new doc page, check this list:

- [ ] Which header category does it belong under? (If none fits, either add a header category or rethink whether this page is really needed.)
- [ ] Which sidebar section inside that header category?
- [ ] Does the target directory exist? If yes, does it have an `index.mdx`?
- [ ] Have you set `sidebar_position` in the frontmatter?
- [ ] Is the file name in kebab-case?
- [ ] For bilingual projects: have you created the matching file under `src/content/docs-ja/` (or added `generated: true` if it is skipped)?

## Category Top Page (index.mdx)

Every category directory should have an authored `index.mdx`. This file is the **landing page** for that category — keep it short:

- A 1–2 sentence intro describing what the category covers.
- A `<CategoryNav category="<category-path>" />` component for a tree category, or `<NoteTrayIndex />` for a declared note tray.
- **No full content or prose beyond the intro.** Real documentation lives in sibling `.mdx` files under the same directory.

The `category` prop value is the directory path relative to the docs content root. Use a single segment for a top-level category (for example, `category="reference"`) or a slash-separated path for a nested category (for example, `category="changelog/core"`). Do not include `src/content/docs/` or a leading slash.

Example `index.mdx` for a `guides/` category:

```mdx
---
title: Guides
sidebar_position: 1
---

Step-by-step guides for common zudo-doc tasks.

<CategoryNav category="guides" />
```

## Checklist for Adding a New Category

Before creating any new category directory:

- [ ] Is this really a new category, or does it belong under an existing one? Default to "fewer categories."
- [ ] Does it need a header nav entry, or is it a nested sidebar category inside an existing header entry?
- [ ] Have you chosen tree vs note-tray shape and created `index.mdx` with the matching list component, a short intro, and `sidebar_position`?
- [ ] If you added a header entry, does its `categoryMatch` value equal the new top-level directory name (single segment)?
- [ ] Does it serve a reader task that no existing category is defined for? Page count alone is not a reason to create or split a category — a small category with a distinct reader task can be right, and a large homogeneous one can stay whole.

## Common Mistakes (Do Not Do)

- **Putting specific pages in the header nav.** The header is for categories, not pages. "Getting Started" ✓, "Installation tutorial" ✗.
- **Deep nesting (4+ levels).** If you find yourself nesting deeply, the header is probably missing a category. (The sidebar renders it; readers struggle with it.)
- **Mixing unrelated topics in one sidebar section.** Split them.
- **Missing `sidebar_position` on pages.** Leads to unpredictable alphabetical order.
- **Missing `index.mdx` in category directories.** The category falls back to a generated index page with a default label and position instead of intentional landing content.
- **Wrapping a linked category in a synthetic `type: "category"`.** It produces an unlinked heading plus a duplicate landing-page child. Keep the real category node.
- **Multi-segment `categoryMatch`** (e.g. `"platforms/xbox"`). Breaks active highlighting — use a single top-level directory name.
- **Reorganizing via config instead of filesystem.** If you are tempted to add a custom sidebar config override, the underlying filesystem is probably wrong. Fix the files instead. Reach for an editorial tree only when existing URLs must stay.
- **Flattening a requested hierarchy into peer links.** A header dropdown, a list of section landing pages, `scopeRoot`, or `initialPath` never creates a parent row. Build the linked tree the request describes.
- **Treating `initialPath: [0]` as a universal index.** It indexes the resolved visible tree. `autogenerated` with `dirName` hides that directory's row, so `[0]` becomes its first child.
- **Using `<CategoryNav>` for a note tray.** It loses tray-specific ranks, dates, and ordering; use `<NoteTrayIndex>`.
- **Stuffing a category `index.mdx` with full content/prose.** The index is a landing page — keep it to a short intro plus the shape-appropriate list component and put real content in sibling files.

## When in Doubt

If you are not sure whether a page belongs in header, sidebar, or nested sidebar: **ask for the current navigation tree first**, draw it out, and place the new page where it fits the hierarchy. Never add pages to "whatever directory is closest" without considering the whole structure.