Sidebar configuration

Your sidebar mirrors your folder structure. Folders are categories, files are pages. You control labels, positions, icons, and behavior with _category_.json files.

How it gets built

Docsio walks your docs/ directory and:

1. Top-level files (e.g. intro.mdx) become top-level sidebar items.
2. Folders become categories. Each category needs _category_.json for its label and behavior.
3. Files inside folders become items inside that category.
4. Nested folders become nested categories.
5. Order is set by sidebar_position (pages) and position (categories). Ties break alphabetically.

_category_.json schema

{
  "label": "Getting Started",
  "position": 1,
  "collapsed": false,
  "collapsible": true,
  "customProps": {
    "icon": "rocket"
  },
  "link": {
    "type": "generated-index",
    "description": "Start here. Five minutes to a published docs site."
  }
}

Fields

• label (string, required) — what shows in the sidebar.
• position (number) — order among other categories at the same level.
• collapsed (boolean, default true) — start collapsed (true) or expanded (false).
• collapsible (boolean, default true) — set false if you don't want users to be able to collapse the category.
• customProps.icon (string) — Phosphor icon name shown next to the label.
• link (object) — what happens when the user clicks the category itself.

link.type options

generated-index — auto-generates a category landing page with a grid of cards for each page inside. Easy default; what we use across most of these docs.

{
  "label": "Features",
  "link": {
    "type": "generated-index",
    "description": "Everything Docsio can do."
  }
}

doc — link to a specific page when the category is clicked. Useful if you have a hand-written category overview.

{
  "label": "API Reference",
  "link": {
    "type": "doc",
    "id": "api-reference/overview"
  }
}

No link field — clicking the category just expands/collapses it without navigating.

Custom sidebar (advanced)

The default sidebar mirrors your folder structure. If you want a custom shape — pages from different folders grouped together, or a totally hand-curated order — edit sidebars.ts in your project:

const sidebars: SidebarsConfig = {
  docsSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Get started',
      items: ['getting-started/quickstart', 'getting-started/installation'],
    },
    {
      type: 'category',
      label: 'Features',
      link: { type: 'generated-index' },
      items: ['features/search', 'features/auth'],
    },
  ],
};

Most users don't need this — the auto-generated sidebar from folders handles 95% of cases.

Reordering pages

Use sidebar_position in each page's frontmatter:

---
title: Quickstart
sidebar_position: 1
---

Lower numbers come first. If two pages have the same number (or no number), they sort alphabetically.

Hiding pages

Three options:

• sidebar_class_name: hidden in frontmatter — hides from sidebar, keeps URL accessible.
• draft: true in frontmatter — hides from sidebar AND search.
• Move the file outside docs/ — docs at non-docs/ paths aren't auto-included in the sidebar.

Categories with one page

A category folder with just one page renders as a flat sidebar item (no nested expander). Useful when you want a top-level page that has its own URL slug different from the folder name.

Tips

• Don't go more than two levels deep. Sub-sub-categories are confusing. Most well-organized docs are one level deep.
• Keep labels short. "Get started" beats "Getting started with our platform."
• Ordering by importance, not alphabet. What does someone need first? Set position: 1 on that page.
• Icons help. Pages with icons in the sidebar are easier to scan. Use Phosphor icons that match each page's role.