zudo-doc

Type to search...

to open search from anywhere

EN/JA/DE

Sidebar

CreatedMar 11, 2026Takeshi Takatsudo

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
---

💡 Tip

Always set sidebar_position explicitly to control page order. Without it, pages are sorted alphabetically, which may not match your intended reading order.

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.

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
---

💡 Tip

The sidebar_label only affects the sidebar. The page title and heading still use title.

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
  guides/                  → "Guides"
    index.mdx              → category index (sidebar_position: 1)
    writing-docs.mdx       → sidebar_position: 1
    color-schemes.mdx      → sidebar_position: 2

📝 Note

The sidebar only supports one level of nesting. Subdirectories within a category directory are not supported.

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" },
  ],
}

💡 Tip

For changelog-style categories, combine sortOrder: "desc" with date-prefixed filenames (e.g., 2026-03-10-release.mdx) for automatic newest-first ordering without manually setting sidebar_position.

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