Sidebar

How the sidebar navigation is structured and configured.

Item Ordering

Pages within a category are sorted by the sidebar_position frontmatter field. Lower values appear first.

Pages without sidebar_position default to 999 and appear at the end of the category, sorted alphabetically by filename.

---
title: My Page
sidebar_position: 3
---

Category Ordering

Categories in the sidebar are ordered by the sidebar_position of their index page (index.mdx). If a category has no index page or no sidebar_position, it falls back to alphabetical ordering.

For example, to make “Getting Started” appear first and “Guides” second:

getting-started/index.mdx  → sidebar_position: 0
guides/index.mdx            → sidebar_position: 1
reference/index.mdx         → sidebar_position: 2

Category Index Pages

Creating an index.mdx inside a directory gives the category a landing page. The category name in the sidebar becomes a clickable link to this page.

A typical category index page uses the <CategoryNav /> component to automatically list all pages in the category:

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

Explore our guides to learn about zudo-doc features.

<CategoryNav category="guides" />

The <CategoryNav /> component renders a grid of links to all pages in the category (excluding the index itself), sorted by sidebar_position.

Without an index.mdx, the category heading is a toggle-only control — clicking it expands or collapses the category, but does not navigate anywhere.

Default Open/Closed

Categories automatically open when the current page is inside them. All other categories are collapsed by default.

Sidebar Label

Use the sidebar_label frontmatter field to display a different label in the sidebar than the page title. This is useful when the full title is too long for the sidebar.

---
title: Getting Started with zudo-doc Installation
sidebar_label: Installation
sidebar_position: 2
---

Directory Structure

Directories inside src/content/docs/ become sidebar categories. The directory name is converted from kebab-case to Title Case automatically.

src/content/docs/
  getting-started/         → "Getting Started"
    index.mdx              → category index (sidebar_position: 0)
    introduction.mdx       → sidebar_position: 1
    installation.mdx       → sidebar_position: 2
    writing-docs.mdx       → sidebar_position: 3
  guides/                  → "Guides"
    index.mdx              → category index (sidebar_position: 1)
    configuration.mdx      → sidebar_position: 1
    frontmatter.mdx        → sidebar_position: 2

Nested Categories (Sub-Groups)

Subdirectories within a category directory create nested collapsible groups in the sidebar. Each sub-directory needs a _category_.json file to set its label and position:

src/content/docs/
  methodology/
    index.mdx
    architecture/
      _category_.json       → { "label": "Architecture", "position": 1, "noPage": true }
      bem-strategy.mdx
      component-first.mdx
    design-systems/
      _category_.json       → { "label": "Design Systems", "position": 2, "noPage": true }
      tight-token.mdx
      two-tier-size.mdx

With auto-generated sidebar, this renders as 3 levels deep:

Methodology            (depth 0)
  ▸ Architecture       (depth 1, collapsible)
    BEM Strategy       (depth 2)
    Component First    (depth 2)
  ▸ Design Systems     (depth 1, collapsible)
    Tight Token        (depth 2)
    Two-Tier Size      (depth 2)

Flattening with Explicit Sidebar Config

For better readability, use explicit sidebar configuration in src/config/sidebars.ts to promote sub-groups to the top level. This reduces nesting by one level:

const sidebars: SidebarsConfig = {
  methodology: [
    "methodology",
    {
      type: "category",
      label: "Architecture",
      items: [{ type: "autogenerated", dirName: "methodology/architecture" }],
    },
    {
      type: "category",
      label: "Design Systems",
      items: [{ type: "autogenerated", dirName: "methodology/design-systems" }],
    },
  ],
};

This renders as 2 levels:

Methodology            (depth 0, leaf link)
▸ Architecture         (depth 0, collapsible)
  BEM Strategy         (depth 1)
  Component First      (depth 1)
▸ Design Systems       (depth 0, collapsible)
  Tight Token          (depth 1)
  Two-Tier Size        (depth 1)

Key points:

• The string "methodology" references the category index page as a leaf link (children are stripped automatically — the explicit config handles structure)
• type: "autogenerated" with dirName pulls articles from a specific subdirectory
• Sub-group categories render at depth 0 with bold labels and border separators
• Articles render at depth 1 — one level flatter than auto-generated

Sort Order (Ascending / Descending)

By default, items within a category are sorted in ascending order (lowest sidebar_position first, then alphabetical). You can reverse this to descending order per category using _category_.json:

{
  "label": "Changelog",
  "position": 10,
  "sortOrder": "desc"
}

When sortOrder is "desc", items are sorted in reverse — highest position first, then reverse alphabetical. This is useful for date-based content (changelogs, release notes) where the newest items should appear at the top.

You can also set sortOrder in src/config/sidebars.ts for manual sidebar configurations:

{
  type: "category",
  label: "Releases",
  sortOrder: "desc",
  items: [
    { type: "autogenerated" },
  ],
}

Ordering Recommendations

• Set sidebar_position on every page for predictable ordering
• Use sidebar_position: 0 on category index pages
• Use sequential numbers (1, 2, 3…) for pages within each category
• Leave gaps between numbers (e.g., 10, 20, 30) if you expect to insert pages later
• Use sortOrder: "desc" in _category_.json for newest-first categories