Skip to main content

Designing the sidebar

The sidebar is the most-used UI on a docs site. It's how every reader navigates. It's also the first thing that tells a new visitor whether your docs are well-organized or a graveyard of half-finished ideas. Treat it like product UI, not like an afterthought.

The structure principles that hold up

1. Top-level categories are nouns or short verbs. "Editor", "Branding", "Publishing", "Reference". Not "How to use the editor" or "About branding". Categories should answer "where would I look for X" — not "what do you want to teach me".

2. Five to ten top-level categories. Below five and you're under-categorizing (one big bucket of pages). Above ten and the sidebar overwhelms. Docsio's own docs run nine. Mintlify's run ten. Stripe's run six (each enormous).

3. Pages within a category should be a flat list, not nested. If a category has more than 8–10 pages, the answer is usually a subcategory or splitting the category — not deeper nesting. Two-level deep is the working ceiling.

4. Order pages by frequency-of-use, not topic. The first page in each category should be the one most people land on. The last should be the obscure setting nobody hits unless they're already lost.

The mistakes everyone makes

  • A "Getting started" category that's secretly the entire docs. When 60% of your pages are inside one category, the categorization isn't doing work.
  • Category labels that explain themselves. "Authentication & Authorization (auth)" is two words too long. Just "Auth".
  • Capitalizing every word like it's the SaaS-company '00s. "How To Configure" reads dated. Sentence case ("How to configure") reads modern.
  • Hidden pages no one removes. Drafts, deprecated pages, "we'll get to it later". Either ship or delete.

Making it work in Docsio

Each top-level folder under docs/ is a sidebar category. The order, label, icon, and description all live in _category_.json:

{
  "label": "The editor",
  "position": 2,
  "collapsible": false,
  "collapsed": false,
  "customProps": { "icon": "pencil-simple" },
  "link": {
    "type": "generated-index",
    "description": "Tour every part of the Docsio editor."
  }
}

collapsible: false means the category is permanently expanded — readers see all pages at a glance. We recommend this for docs sites under 80 pages. Past that, switch to collapsible categories so the sidebar isn't a wall of text.

Within a category, page order comes from the sidebar_position frontmatter on each .md/.mdx file. Lower numbers go higher.

Ask the agent

When in doubt, ask the AI agent:

Audit our sidebar — is anything over-nested or out of order?

It'll read the structure, compare against good docs sites, and suggest specific changes. You don't have to take all of them. The exercise of being told "this category has 14 pages, that's too many" is the value.