How to Structure Navigations

Best practices for organizing header navigation and sidebar categories

Overview

zudo-doc uses a 3-level navigation hierarchy to organize content:

1. Header navigation — the broadest, top-level categories visible across the entire site

2. Sidebar — the next level of categorization within each header nav section

3. Nested sidebar categories — detailed subcategories inside sidebar sections

Each level narrows the scope. The header gives users a high-level map of the site, the sidebar breaks a section into logical groups, and nested categories add fine-grained structure where needed.

File Structure = Navigation Structure

Keep your file structure and navigation structure tightly coupled. If you want a sidebar category called "Hardware," create a hardware/ directory. If you want a header nav item for "Guides," create a guides/ directory and set categoryMatch: "guides". The directory name, the URL path, and the nav label should all align.

This tight coupling is the recommended approach because:

• Predictability — you always know where a page will appear in the navigation by looking at where the file lives

• No drift — there is no separate config that can get out of sync with the actual content

• AI-friendly — AI tools can reliably generate correct navigation by following the directory structure convention

While zudo-doc supports advanced configuration for complex cases (custom sidebar labels, sort overrides, nested dropdowns), the default behavior — directories become categories, files become pages — covers most needs. Start simple and only add complexity when the default mapping is not enough.

Header Navigation Rules

The header navigation is the topmost level. It should contain only the broadest categories that define your site's major sections.

• Keep it concise — aim for 3–6 items. More than that overwhelms users and clutters the header.

• Use dropdowns sparingly — only for closely related sections that belong under a single umbrella (e.g., "Learn" containing "Guides" and "Components").

• Each item maps to a content directory — the categoryMatch field in your config links a header item to the sidebar content for that section.

Example Header Config

// src/config/settings.ts
export const settings = {
  headerNav: [
    { label: "Getting Started", path: "/docs/getting-started", categoryMatch: "getting-started" },
    {
      label: "Learn",
      path: "/docs/guides",
      categoryMatch: "guides",
      children: [
        { label: "Guides", path: "/docs/guides", categoryMatch: "guides" },
        { label: "Components", path: "/docs/components", categoryMatch: "components" },
      ],
    },
    { label: "Reference", path: "/docs/reference", categoryMatch: "reference" },
  ],
};

Sidebar Structure Rules

The sidebar provides the next level of categorization within each header nav section. It is generated automatically from your directory structure.

• Use directories for categories — each directory becomes a collapsible sidebar group.

• Every category directory should have an index.mdx — this serves as the landing page for that category and sets its sidebar_position.

• Keep nesting to 2–3 levels max — deeply nested sidebars are hard to navigate and often signal that content needs reorganization.

• Set sidebar_position on every page — this ensures predictable ordering instead of relying on alphabetical defaults.

Directory-to-Sidebar Mapping

src/content/docs/guides/        ← sidebar category "Guides"
├── index.mdx                   ← category landing (sidebar_position: 0)
├── configuration.mdx           ← sidebar_position: 1
├── sidebar.mdx                 ← sidebar_position: 2
└── header-navigation.mdx       ← sidebar_position: 3

Each .mdx file appears as a sidebar item. Subdirectories become nested collapsible categories.

Category Top Page (index.mdx)

Every category directory should have an index.mdx that acts as the landing page for that category. Keep it minimal: a 1–2 sentence description of the category followed by a <CategoryNav> component, which automatically renders links to all sibling pages.

---
title: Guides
sidebar_position: 1
---

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

<CategoryNav category="guides" />

The category prop is the top-level directory name (e.g. "guides" for src/content/docs/guides/). Do not put full documentation content in the index — keep real docs in sibling .mdx files under the same directory.

Concrete Real-World Example

Imagine building a gaming wiki. Here is how you would structure the navigation:

Navigation Plan

Header Nav:
├── Home
├── Platforms              ← dropdown
│   ├── Xbox
│   ├── PlayStation
│   └── Nintendo
├── Genres                 ← dropdown
│   ├── RPG
│   ├── Action
│   └── Strategy
└── Community

When a user clicks "Xbox" in the Platforms dropdown, the sidebar shows:

Sidebar (Xbox section):
├── Overview (index)
├── Hardware
│   ├── Xbox Series X
│   ├── Xbox Series S
│   └── Accessories
├── Games
│   ├── Halo Infinite
│   ├── Forza Horizon 5
│   └── Starfield
└── Services
    ├── Game Pass
    └── Xbox Live

Header Config for Gaming Wiki

Each categoryMatch value must be a single top-level directory name — the framework resolves active state by matching only the first path segment of the current URL.

// src/config/settings.ts
export const settings = {
  headerNav: [
    { label: "Home", path: "/docs/home", categoryMatch: "home" },
    {
      label: "Platforms",
      path: "/docs/xbox",
      categoryMatch: "xbox",
      children: [
        { label: "Xbox", path: "/docs/xbox", categoryMatch: "xbox" },
        { label: "PlayStation", path: "/docs/playstation", categoryMatch: "playstation" },
        { label: "Nintendo", path: "/docs/nintendo", categoryMatch: "nintendo" },
      ],
    },
    {
      label: "Genres",
      path: "/docs/rpg",
      categoryMatch: "rpg",
      children: [
        { label: "RPG", path: "/docs/rpg", categoryMatch: "rpg" },
        { label: "Action", path: "/docs/action", categoryMatch: "action" },
        { label: "Strategy", path: "/docs/strategy", categoryMatch: "strategy" },
      ],
    },
    { label: "Community", path: "/docs/community", categoryMatch: "community" },
  ],
};

Directory Structure for Gaming Wiki

Each platform and genre gets its own top-level directory so that categoryMatch matches the first URL segment correctly:

src/content/docs/
├── home/
│   └── index.mdx
├── xbox/
│   ├── index.mdx                  ← "Overview"
│   ├── hardware/
│   │   ├── index.mdx
│   │   ├── xbox-series-x.mdx
│   │   ├── xbox-series-s.mdx
│   │   └── accessories.mdx
│   ├── games/
│   │   ├── index.mdx
│   │   ├── halo-infinite.mdx
│   │   ├── forza-horizon-5.mdx
│   │   └── starfield.mdx
│   └── services/
│       ├── index.mdx
│       ├── game-pass.mdx
│       └── xbox-live.mdx
├── playstation/
│   └── index.mdx
├── nintendo/
│   └── index.mdx
├── rpg/
│   └── ...
├── action/
│   └── ...
├── strategy/
│   └── ...
└── community/
    └── index.mdx

Common Mistakes

Tips for AI-Assisted Setup

When using AI tools to generate zudo-doc site structures, follow these rules for consistent results:

• Follow the hierarchy strictly — header nav for broad categories, sidebar for subcategories, nested directories for further detail. Never skip a level.

• Keep header nav items to broad categories only — resist the urge to add specific pages to the header. That is what the sidebar is for.

• Match categoryMatch values to actual directory names — a categoryMatch: "guides" must correspond to a src/content/docs/guides/ directory.

• Always create index.mdx for every category directory — this ensures the category has a proper landing page and sidebar entry.

• Set sidebar_position on every page and index — this is the most common thing AI tools forget, leading to unpredictable ordering.

• Use kebab-case for directory and file names — consistent naming avoids case-sensitivity issues across platforms.