[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6D2G4P5TXMJRTAFVAP4QJF6":3,"skill-same:01M6D2G4P5TXMJRTAFVAP4QJF6":75},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":27,"publishedAt":49,"linkOnly":50,"markdownContent":51,"markdownBody":52,"frontMatter":53,"refName":55,"commitSha":56,"skillDirectory":57,"forksCount":58,"repositoryHtmlUrl":59,"repositoryHomepageUrl":6,"ownerHtmlUrl":60,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":61,"install":62,"resources":74},"01M6D2G4P5TXMJRTAFVAP4QJF6","zudo-doc-navigation-design",null,"Navigation design rules for zudo-doc documentation sites. Consult before creating new pages, restructuring directories, or designing header navigation. Covers: the recommended 3-level hierarchy (header → sidebar → nested), filesystem navigation as the default, linked versus heading-only category rows, when an editorial or umbrella tree is warranted, writing the intended tree first, header nav conciseness, category index pages, sidebar_position discipline, and common mistakes. Triggered by 'nav design', 'navigation structure', 'zudo-doc-navigation-design', 'structure nav', 'add category', 'add header nav'.","zudolab\u002Fzudo-doc","zudolab","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F266356510?v=4","01M6D2E9N9X9851YB24CEQF04H","01M6D2E9SFKZ0FWBMPB2625H28",1,"MIT","https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fzudo-doc-navigation-design\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48],"design","navigation design","navigation","zudo doc navigation design","doc","tree","new","when","sites","true","for","directories","mistakes","as","editorial","Rules","writing","only","pages","filesystem","default","2026-11-10 10:12:30",false,"---\nname: zudo-doc-navigation-design\ndescription: \"Navigation design rules for zudo-doc documentation sites. Consult before creating new pages, restructuring directories, or designing header navigation. Covers: the recommended 3-level hierarchy (header → sidebar → nested), filesystem navigation as the default, linked versus heading-only category rows, when an editorial or umbrella tree is warranted, writing the intended tree first, header nav conciseness, category index pages, sidebar_position discipline, and common mistakes. Triggered by 'nav design', 'navigation structure', 'zudo-doc-navigation-design', 'structure nav', 'add category', 'add header nav'.\"\nuser-invocable: true\n---\n\n# zudo-doc Navigation Design Rules\n\n**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.\n\n## Reference Documentation\n\nThis skill is the short version. The authoritative guides are:\n\n- `src\u002Fcontent\u002Fdocs\u002Fgetting-started\u002Fstructuring-navigations.mdx` — choosing a pattern (decision table) and the gaming-wiki walkthrough.\n- `src\u002Fcontent\u002Fdocs\u002Fguides\u002Fsidebar.mdx` — category rows, sidebar item semantics, `initialPath`\u002F`initialPathMode`, `scopeRoot`, and scope recipes.\n- `src\u002Fcontent\u002Fdocs\u002Fguides\u002Feditorial-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.\n- `src\u002Fcontent\u002Fdocs\u002Fguides\u002Fmaintaining-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.\n\nLink to those guides instead of copying their advanced implementation into another file.\n\n## Placement Check Before Adding or Re-scoping Content\n\nTypo, 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:\n\n1. Who can do what with this content?\n2. Does an existing page already serve that role? (Prefer updating it.)\n3. Why this category, and is there a competing destination?\n4. Does this addition change what the category means?\n\nClear 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).\n\n## Write the Intended Tree Before Choosing Configuration\n\nBefore you touch `headerNav`, `sidebars`, or chrome bindings, write down:\n\n1. The complete parent\u002Fchild tree the reader should see, marking each row as linked or heading-only.\n2. 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.\n\nThen pick the pattern that produces that tree. Four patterns look alike and are not interchangeable:\n\n- **Header dropdown** — collects independent sections in the header. It creates no sidebar parent.\n- **Shared sidebar hierarchy** — one linked landing page is the real parent of the rows below it.\n- **Curated editorial tree** — lists particular pages and cross-links; a cross-link stays a leaf (`guides\u002Feditorial-navigation.mdx`).\n- **Umbrella tree** — a shared hierarchy whose children are complete native sections; only the section list is authored (`guides\u002Feditorial-navigation.mdx#umbrella-tree-with-complete-sections`). This showcase's Learn sidebar is one (`src\u002Flib\u002Flearn-navigation.ts`, `src\u002Flib\u002Flearn-chrome.tsx`).\n\nWhen 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.\n\n## The 3-Level Hierarchy\n\nDesign 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:\n\n1. **Header nav** — the biggest categories (3–6 items max)\n2. **Sidebar** — all pages in the active category (generated from the filesystem)\n3. **Nested sidebar categories** — subsections within a sidebar (2–3 levels of nesting max)\n\nEach 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.\n\n## File Structure Is the Default Navigation\n\n**This is the single most important rule.** By default, the directory tree under `src\u002Fcontent\u002Fdocs\u002F` *is* the navigation, with no separate config to keep in sync. Recommend this default first.\n\n- A directory becomes a sidebar category. Its `index.mdx` is the category landing page.\n- A file becomes a sidebar item.\n- Subdirectories become nested collapsible categories.\n- The `headerNav` setting maps top-level directories to header items via `categoryMatch`.\n\n## Category Shapes\n\nChoose the category shape before writing its index:\n\n- **Tree (default)** — a topic hierarchy that may contain subdirectories. Keep `index.mdx` to a short intro plus `\u003CCategoryNav category=\"\u003Ccategory-path>\" \u002F>`.\n- **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 `\u003CNoteTrayIndex>` instead of `\u003CCategoryNav>`.\n\nNote 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\u002Fmonth grouping requires a dated tray. Keep `sidebar_position` monotonic with `date` as a documented recommendation, not a validation rule.\n\n**Consequence**: design the filesystem with navigation in mind from the start. When the wanted hierarchy differs from the directories, move the files.\n\nEditorial 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\u002Feditorial-navigation.mdx`); recommend it only when moving files is not an option.\n\n## Linked Parents vs Heading-Only Groups\n\nDecide for every group row whether it is a link:\n\n- **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.\n- **Heading-only group** — no page of its own. Use `category_no_page: true` on the `index.mdx`, or a synthetic `{ type: \"category\" }` sidebar item.\n\nA 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.\n\nThe 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.\n\n## Header Navigation Rules\n\nThe header is the topmost level. It holds only the biggest categories.\n\n- **3–6 items max.** More than 6 overwhelms users and wraps the header.\n- **Each item is a broad section, not a page.** \"Guides\" ✓, \"How to install\" ✗.\n- **`categoryMatch` must be a single top-level directory name.** Multi-segment values (e.g. `\"platforms\u002Fxbox\"`) 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\u002Fcore`, `changelog\u002Fcli`) are the canonical example. Children that represent separate top-level directories may each use their own single-segment `categoryMatch`.\n- **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`.\n- **Dropdowns are for closely related sections only.** \"Learn > Guides, Components\" makes sense. \"Everything > 7 miscellaneous items\" does not — split into separate header items instead.\n\n## Sidebar Structure Rules\n\nThe sidebar is generated from the filesystem. The rules are about how you organize files:\n\n- **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`.\n- **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.\n- **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.\n- **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).\n- **Use kebab-case directory and file names.** `my-article.mdx`, not `myArticle.mdx`.\n- **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.\n- **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.\n\n## Checklist for Adding a New Page\n\nBefore creating any new doc page, check this list:\n\n- [ ] Which header category does it belong under? (If none fits, either add a header category or rethink whether this page is really needed.)\n- [ ] Which sidebar section inside that header category?\n- [ ] Does the target directory exist? If yes, does it have an `index.mdx`?\n- [ ] Have you set `sidebar_position` in the frontmatter?\n- [ ] Is the file name in kebab-case?\n- [ ] For bilingual projects: have you created the matching file under `src\u002Fcontent\u002Fdocs-ja\u002F` (or added `generated: true` if it is skipped)?\n\n## Category Top Page (index.mdx)\n\nEvery category directory should have an authored `index.mdx`. This file is the **landing page** for that category — keep it short:\n\n- A 1–2 sentence intro describing what the category covers.\n- A `\u003CCategoryNav category=\"\u003Ccategory-path>\" \u002F>` component for a tree category, or `\u003CNoteTrayIndex \u002F>` for a declared note tray.\n- **No full content or prose beyond the intro.** Real documentation lives in sibling `.mdx` files under the same directory.\n\nThe `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\u002Fcore\"`). Do not include `src\u002Fcontent\u002Fdocs\u002F` or a leading slash.\n\nExample `index.mdx` for a `guides\u002F` category:\n\n```mdx\n---\ntitle: Guides\nsidebar_position: 1\n---\n\nStep-by-step guides for common zudo-doc tasks.\n\n\u003CCategoryNav category=\"guides\" \u002F>\n```\n\n## Checklist for Adding a New Category\n\nBefore creating any new category directory:\n\n- [ ] Is this really a new category, or does it belong under an existing one? Default to \"fewer categories.\"\n- [ ] Does it need a header nav entry, or is it a nested sidebar category inside an existing header entry?\n- [ ] Have you chosen tree vs note-tray shape and created `index.mdx` with the matching list component, a short intro, and `sidebar_position`?\n- [ ] If you added a header entry, does its `categoryMatch` value equal the new top-level directory name (single segment)?\n- [ ] 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.\n\n## Common Mistakes (Do Not Do)\n\n- **Putting specific pages in the header nav.** The header is for categories, not pages. \"Getting Started\" ✓, \"Installation tutorial\" ✗.\n- **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.)\n- **Mixing unrelated topics in one sidebar section.** Split them.\n- **Missing `sidebar_position` on pages.** Leads to unpredictable alphabetical order.\n- **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.\n- **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.\n- **Multi-segment `categoryMatch`** (e.g. `\"platforms\u002Fxbox\"`). Breaks active highlighting — use a single top-level directory name.\n- **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.\n- **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.\n- **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.\n- **Using `\u003CCategoryNav>` for a note tray.** It loses tray-specific ranks, dates, and ordering; use `\u003CNoteTrayIndex>`.\n- **Stuffing a category `index.mdx` with full content\u002Fprose.** 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.\n\n## When in Doubt\n\nIf 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.\n","# zudo-doc Navigation Design Rules\n\n**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.\n\n## Reference Documentation\n\nThis skill is the short version. The authoritative guides are:\n\n- `src\u002Fcontent\u002Fdocs\u002Fgetting-started\u002Fstructuring-navigations.mdx` — choosing a pattern (decision table) and the gaming-wiki walkthrough.\n- `src\u002Fcontent\u002Fdocs\u002Fguides\u002Fsidebar.mdx` — category rows, sidebar item semantics, `initialPath`\u002F`initialPathMode`, `scopeRoot`, and scope recipes.\n- `src\u002Fcontent\u002Fdocs\u002Fguides\u002Feditorial-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.\n- `src\u002Fcontent\u002Fdocs\u002Fguides\u002Fmaintaining-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.\n\nLink to those guides instead of copying their advanced implementation into another file.\n\n## Placement Check Before Adding or Re-scoping Content\n\nTypo, 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:\n\n1. Who can do what with this content?\n2. Does an existing page already serve that role? (Prefer updating it.)\n3. Why this category, and is there a competing destination?\n4. Does this addition change what the category means?\n\nClear 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).\n\n## Write the Intended Tree Before Choosing Configuration\n\nBefore you touch `headerNav`, `sidebars`, or chrome bindings, write down:\n\n1. The complete parent\u002Fchild tree the reader should see, marking each row as linked or heading-only.\n2. 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.\n\nThen pick the pattern that produces that tree. Four patterns look alike and are not interchangeable:\n\n- **Header dropdown** — collects independent sections in the header. It creates no sidebar parent.\n- **Shared sidebar hierarchy** — one linked landing page is the real parent of the rows below it.\n- **Curated editorial tree** — lists particular pages and cross-links; a cross-link stays a leaf (`guides\u002Feditorial-navigation.mdx`).\n- **Umbrella tree** — a shared hierarchy whose children are complete native sections; only the section list is authored (`guides\u002Feditorial-navigation.mdx#umbrella-tree-with-complete-sections`). This showcase's Learn sidebar is one (`src\u002Flib\u002Flearn-navigation.ts`, `src\u002Flib\u002Flearn-chrome.tsx`).\n\nWhen 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.\n\n## The 3-Level Hierarchy\n\nDesign 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:\n\n1. **Header nav** — the biggest categories (3–6 items max)\n2. **Sidebar** — all pages in the active category (generated from the filesystem)\n3. **Nested sidebar categories** — subsections within a sidebar (2–3 levels of nesting max)\n\nEach 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.\n\n## File Structure Is the Default Navigation\n\n**This is the single most important rule.** By default, the directory tree under `src\u002Fcontent\u002Fdocs\u002F` *is* the navigation, with no separate config to keep in sync. Recommend this default first.\n\n- A directory becomes a sidebar category. Its `index.mdx` is the category landing page.\n- A file becomes a sidebar item.\n- Subdirectories become nested collapsible categories.\n- The `headerNav` setting maps top-level directories to header items via `categoryMatch`.\n\n## Category Shapes\n\nChoose the category shape before writing its index:\n\n- **Tree (default)** — a topic hierarchy that may contain subdirectories. Keep `index.mdx` to a short intro plus `\u003CCategoryNav category=\"\u003Ccategory-path>\" \u002F>`.\n- **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 `\u003CNoteTrayIndex>` instead of `\u003CCategoryNav>`.\n\nNote 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\u002Fmonth grouping requires a dated tray. Keep `sidebar_position` monotonic with `date` as a documented recommendation, not a validation rule.\n\n**Consequence**: design the filesystem with navigation in mind from the start. When the wanted hierarchy differs from the directories, move the files.\n\nEditorial 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\u002Feditorial-navigation.mdx`); recommend it only when moving files is not an option.\n\n## Linked Parents vs Heading-Only Groups\n\nDecide for every group row whether it is a link:\n\n- **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.\n- **Heading-only group** — no page of its own. Use `category_no_page: true` on the `index.mdx`, or a synthetic `{ type: \"category\" }` sidebar item.\n\nA 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.\n\nThe 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.\n\n## Header Navigation Rules\n\nThe header is the topmost level. It holds only the biggest categories.\n\n- **3–6 items max.** More than 6 overwhelms users and wraps the header.\n- **Each item is a broad section, not a page.** \"Guides\" ✓, \"How to install\" ✗.\n- **`categoryMatch` must be a single top-level directory name.** Multi-segment values (e.g. `\"platforms\u002Fxbox\"`) 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\u002Fcore`, `changelog\u002Fcli`) are the canonical example. Children that represent separate top-level directories may each use their own single-segment `categoryMatch`.\n- **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`.\n- **Dropdowns are for closely related sections only.** \"Learn > Guides, Components\" makes sense. \"Everything > 7 miscellaneous items\" does not — split into separate header items instead.\n\n## Sidebar Structure Rules\n\nThe sidebar is generated from the filesystem. The rules are about how you organize files:\n\n- **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`.\n- **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.\n- **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.\n- **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).\n- **Use kebab-case directory and file names.** `my-article.mdx`, not `myArticle.mdx`.\n- **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.\n- **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.\n\n## Checklist for Adding a New Page\n\nBefore creating any new doc page, check this list:\n\n- [ ] Which header category does it belong under? (If none fits, either add a header category or rethink whether this page is really needed.)\n- [ ] Which sidebar section inside that header category?\n- [ ] Does the target directory exist? If yes, does it have an `index.mdx`?\n- [ ] Have you set `sidebar_position` in the frontmatter?\n- [ ] Is the file name in kebab-case?\n- [ ] For bilingual projects: have you created the matching file under `src\u002Fcontent\u002Fdocs-ja\u002F` (or added `generated: true` if it is skipped)?\n\n## Category Top Page (index.mdx)\n\nEvery category directory should have an authored `index.mdx`. This file is the **landing page** for that category — keep it short:\n\n- A 1–2 sentence intro describing what the category covers.\n- A `\u003CCategoryNav category=\"\u003Ccategory-path>\" \u002F>` component for a tree category, or `\u003CNoteTrayIndex \u002F>` for a declared note tray.\n- **No full content or prose beyond the intro.** Real documentation lives in sibling `.mdx` files under the same directory.\n\nThe `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\u002Fcore\"`). Do not include `src\u002Fcontent\u002Fdocs\u002F` or a leading slash.\n\nExample `index.mdx` for a `guides\u002F` category:\n\n```mdx\n---\ntitle: Guides\nsidebar_position: 1\n---\n\nStep-by-step guides for common zudo-doc tasks.\n\n\u003CCategoryNav category=\"guides\" \u002F>\n```\n\n## Checklist for Adding a New Category\n\nBefore creating any new category directory:\n\n- [ ] Is this really a new category, or does it belong under an existing one? Default to \"fewer categories.\"\n- [ ] Does it need a header nav entry, or is it a nested sidebar category inside an existing header entry?\n- [ ] Have you chosen tree vs note-tray shape and created `index.mdx` with the matching list component, a short intro, and `sidebar_position`?\n- [ ] If you added a header entry, does its `categoryMatch` value equal the new top-level directory name (single segment)?\n- [ ] 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.\n\n## Common Mistakes (Do Not Do)\n\n- **Putting specific pages in the header nav.** The header is for categories, not pages. \"Getting Started\" ✓, \"Installation tutorial\" ✗.\n- **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.)\n- **Mixing unrelated topics in one sidebar section.** Split them.\n- **Missing `sidebar_position` on pages.** Leads to unpredictable alphabetical order.\n- **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.\n- **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.\n- **Multi-segment `categoryMatch`** (e.g. `\"platforms\u002Fxbox\"`). Breaks active highlighting — use a single top-level directory name.\n- **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.\n- **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.\n- **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.\n- **Using `\u003CCategoryNav>` for a note tray.** It loses tray-specific ranks, dates, and ordering; use `\u003CNoteTrayIndex>`.\n- **Stuffing a category `index.mdx` with full content\u002Fprose.** 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.\n\n## When in Doubt\n\nIf 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.\n",{"name":5,"description":7,"user-invocable":54},true,"main","4062ac5c581df130656e2a6bfabe6d680077a594",".claude\u002Fskills\u002Fzudo-doc-navigation-design",0,"https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc","https:\u002F\u002Fgithub.com\u002Fzudolab","2026-11-13 03:37:18",{"source":8,"skillName":5,"commands":63,"prompt":73,"zipAvailable":54},[64,67,70],{"tool":65,"command":66},"npx","npx skills add zudolab\u002Fzudo-doc --skill zudo-doc-navigation-design",{"tool":68,"command":69},"bunx","bunx skills add zudolab\u002Fzudo-doc --skill zudo-doc-navigation-design",{"tool":71,"command":72},"pnpm","pnpm dlx skills add zudolab\u002Fzudo-doc --skill zudo-doc-navigation-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fzudo-doc-navigation-design\u002FSKILL.md",[],[76,103,130,146,178,190],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":88,"publishedAt":49},"01M6D2GZKKY2E651Q297NEZEGV","zudo-doc-writing","Doc-writing and navigation-structure guide for this zudo-doc project. Consult BEFORE creating pages, adding categories, designing header navigation, or writing\u002Fediting mdx content under src\u002Fcontent\u002F. Covers: reading the AUTHORING.md editorial policy and its four placement questions, when to run a structure review, plan-the-nav-tree-first workflow, tree vs note-tray categories, the recommended 3-level hierarchy (header → sidebar → nested), filesystem navigation as the default, linked versus heading-only category rows, category index pages, sidebar_position discipline, frontmatter schema, no-h1 rule, relative .mdx links, and admonition syntax. Triggered by 'write docs', 'add a page', 'create a page', 'add category', 'structure navigation', 'nav design', 'zudo-doc-writing'.","https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002Fpackages\u002Fcreate-zudo-doc\u002Ftemplates\u002Ffeatures\u002FclaudeSkillsWriting\u002Ffiles\u002F.claude\u002Fskills\u002Fzudo-doc-writing\u002FSKILL.md",[82,85],{"categoryNo":83,"categoryName":84,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":86,"categoryName":87,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000036","内容创作者",[44,89,32,90,48,28,45,91,92,93,94,95,96,97,35,98,99,100,101,102],"zudo doc writing","project","workflow","consult","create","structure","plan","discipline","categories","review","hierarchy","filesystem navigation","run","src",{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":49},"01M6D2GWFZ81SCB168Z4P4NYYN","zudo-doc-version-bump","Bump package version, update changelog and versioned docs snapshot (if those features are enabled), commit, tag, and create a GitHub release. Use when: (1) User says 'version bump', 'bump version', 'release', or 'zudo-doc-version-bump', (2) User wants to create a new release of this project.","https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002Fpackages\u002Fcreate-zudo-doc\u002Ftemplates\u002Ffeatures\u002FclaudeSkills\u002Ffiles\u002F.claude\u002Fskills\u002Fzudo-doc-version-bump\u002FSKILL.md",[],[110,111,112,113,32,90,114,115,116,117,118,93,119,120,121,122,123,124,125,126,127,34,35,128,129],"bump","zudo doc version bump","version","version bump","update changelog","package","use","patch","commit","changelog","github","update","release","snapshot","bump version","docs","user","proposal","features","github release",{"skillNo":131,"name":132,"nameZh":6,"description":133,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":134,"categories":135,"keywords":136,"publishedAt":49},"01M6D2GRJ1MKMMEACKDFSAKF20","zudo-doc-translate","Translate zudo-doc documentation between the locales configured in this project, with Japanese conventions applied only to the `ja` locale.","https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002Fpackages\u002Fcreate-zudo-doc\u002Ftemplates\u002Ffeatures\u002FclaudeSkills\u002Ffiles\u002F.claude\u002Fskills\u002Fzudo-doc-translate\u002FSKILL.md",[],[137,138,32,139,140,141,90,45,142,125,143,144,145],"translate","zudo doc translate","documentation","i18n","japanese","conventions","translate docs","with","locale",{"skillNo":147,"name":148,"nameZh":6,"description":149,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":150,"categories":151,"keywords":157,"publishedAt":49},"01M6D2GMXQGVKJZTA35Q9AZN7V","zudo-doc-design-system","Project-specific CSS and component rules for zudo-doc. Must be consulted before writing or editing CSS, zudo-wind utilities, color tokens, or component markup in this project. Covers: component-first strategy, design token system, three-tier color architecture, and palette index convention. Triggered by 'design system', 'zudo-doc-design-system', 'zudo-doc-css-wisdom' (old name).","https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002Fpackages\u002Fcreate-zudo-doc\u002Ftemplates\u002Ffeatures\u002FclaudeSkills\u002Ffiles\u002F.claude\u002Fskills\u002Fzudo-doc-design-system\u002FSKILL.md",[152,155,156],{"categoryNo":153,"categoryName":154,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},[158,159,28,32,160,161,162,90,163,164,165,44,166,43,167,168,169,170,171,172,173,174,175,176,177,38],"zudo doc design system","system","design system","css","three","editing","tokens","strategy","wisdom","architecture","component","first","token","design-system","index","design token","wind","palette","Utilities","color",{"skillNo":179,"name":180,"nameZh":6,"description":181,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":182,"categories":183,"keywords":184,"publishedAt":49},"01M6D2GJYJQRZTHVY1CN884E96","localized-shell","Fixture skill for localized generated resource routes.","https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002Fe2e\u002Ffixtures\u002Fi18n\u002Fsrc\u002Fcontent\u002Fresources\u002F.claude\u002Fskills\u002Flocalized-shell\u002FSKILL.md",[],[185,186,187,188,189,38],"localized shell","shell","fixture","generated","fixture skill",{"skillNo":191,"name":192,"nameZh":6,"description":193,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":194,"categories":195,"keywords":198,"publishedAt":49},"01M6D2GF8BK70Y7TE3B7NCX87H","zudo-doc-writing-rules","Doc-writing rules for zudo-doc content (mdx files under src\u002Fcontent\u002Fdocs\u002F and src\u002Fcontent\u002Fdocs-ja\u002F). Consult before writing or editing doc content. Covers: no h1 in content, sidebar_position is mandatory, kebab-case file names, bilingual rule, linking conventions, and admonition syntax. Triggered by 'writing rules', 'zudo-doc-writing-rules', 'doc rule', 'mdx rule', 'write a doc', 'create a page'.","https:\u002F\u002Fgithub.com\u002Fzudolab\u002Fzudo-doc\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fzudo-doc-writing-rules\u002FSKILL.md",[196,197],{"categoryNo":83,"categoryName":84,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":86,"categoryName":87,"taxonomyType":25,"taxonomyTypeDesc":26},[199,32,44,43,89,200,93,201,163,102,202,203,142,204,205,92,38,37,206,207],"zudo doc writing rules","writing rules","page","write","syntax","files","file","case","linking"]