Navigation IA

The docs sidebar is the contract you make with a reader: "here's the shape of what we document, pick a starting point". Bad IA reads like a sitemap dump. Good IA has hierarchy that matches how users think about the product. This guide covers the principles; for the config syntax, see navigation configuration.

First principle: match user mental models

Docs IA fails when it mirrors your internal team structure instead of users' tasks.

❌ Organised by team that built it
├── Platform Team
│   ├── Auth
│   ├── Rate limiting
│   └── Multi-region
├── Integrations Team
│   ├── Slack
│   └── Stripe
└── AI Team
    ├── Assistant
    └── Embeddings

✅ Organised by user task
├── Get Started
├── Authenticate
├── Common Integrations
│   ├── Slack
│   └── Stripe
├── AI Features
└── Deployment

Users come to docs with a job to do, not an org chart in mind.

The three shapes of docs IA

Most documentation sites fit one of three shapes:

The two-click rule

From any landing page, the user should reach the content they want in two clicks: pick a section, pick a page.

Docs landing page
├── Click 1: "Deploy"         (top-level nav)
└── Click 2: "Custom domain"  (sidebar page)
= target page reached

Three clicks is okay but indicates the section could split. Four is too many — the reader either gives up or falls back to search.

Corollary: if your sidebar has three levels of nesting, flatten one. Users don't read past the second indent level. Either:

• Merge sibling groups together.

• Split the nested group into its own top-level tab.

• Move the contents of the deepest groups into their parent (flatten the tree by one level).

Group granularity

Too broad

├── Documentation     (200+ pages, everything the product has)

One group for 200 pages means every page is equally visible — which means none of them are. Readers' eyes glaze.

Too narrow

├── Authentication
├── OAuth 2.0
├── JWT
├── API Keys
├── Session Cookies
├── Webhook Signatures
├── Password Hashing
├── ...

Seven groups for what's really one topic (auth). Fragmented + distracting.

Right

├── Authentication
│   ├── API keys
│   ├── OAuth 2.0
│   ├── JWT tokens
│   └── Webhook signatures

One group covering the domain. Sub-pages for distinct topics within. Reader skims the group header, finds the right page one level down.

Rule of thumb: 5-12 pages per group is the sweet spot. Less than 5 — consider merging with a sibling group. More than 12 — split or nest.

Section order matters

Sidebar order = reading order for first-time visitors. The default reading journey should make sense:

Tabs vs groups

NookDocs supports tabs (top-level horizontal nav) AND groups (sidebar sections). When to use which:

Rule of thumb: 3-6 tabs. Fewer than 3 isn't using the tab system; more than 6 crowds the top bar on mobile.

Drill-down vs expand-all

NookDocs supports two sidebar behaviours — the default varies by theme:

Expand-all (drill-down: false)

Every group label is a toggle. Click to expand. State persists per-session. Only one group expanded at a time is common.

Works well for:

• Reference-heavy docs where readers know what they're looking for.

• Large sidebars (20+ groups) where showing everything is overwhelming.

Drill-down (drill-down: true, group.root set)

Group label is a link. Click navigates to a group landing page. Sidebar shows the current section's pages only.

Works well for:

• Task-first IA where each section is a distinct topic with its own landing.

• Marketing-adjacent docs where the "group landing" can pitch what's inside.

Configure via interaction.drilldown + per-group root frontmatter.

Nested groups — use sparingly

Nested groups create three-level hierarchy in the sidebar:

Tab                      (top nav)
└── Group                (bold label)
    ├── Subgroup         (bold label, indented)
    │   ├── Page         (link)
    │   └── Page
    └── Subgroup

Cost: readers' eyes stop at level 2 (depth-of-field drops off fast). Pages buried in subgroups get less traffic.

Use nesting when: the taxonomy really has three levels (e.g. Integrations → Analytics → 13 providers). 16 flat "Integrations" pages is harder to scan than "Analytics (13) + Privacy (1) + Support (2)".

Avoid nesting when: there are only 2-4 pages in the subgroup. Flatten. We flattened NookDocs's own Integrations IA after realising the subgroup labels added noise.

Tab naming

Tabs have ~60 chars total on desktop, ~30 on mobile before truncation. Keep each tab name 1-2 words:

Two-word tabs beat one-word when the one-word is generic ("Docs", "Info", "Resources" — all meaningless). Three-word tabs are almost always over-explaining.

Group label naming

Same discipline. 1-2 words describing the topic, not the team or the abstraction:

Verbs-as-labels ("Deploy", "Authenticate", "Customise") read more clearly than nouns-as-labels ("Deployment", "Authentication", "Customisation") because they match user intent.

Empty-state + orphan audits

Monthly IA hygiene:

Mobile considerations

On mobile, the sidebar lives behind a hamburger. Opening the menu is one tap; finding the target is the hard part.

• Tab strip horizontal scroll — all tabs reachable via swipe. Don't let tab count blow past 6.

• Groups collapse by default on mobile — readers see group headers, tap to expand. Keeps initial view scannable.

• Search takes priority — on mobile, most users search instead of browse. Make the search affordance prominent.

Topical clusters = SEO

IA choices affect SEO (see linking guide). Strong topical clusters — pillar + supporting pages grouped together — signal topical authority. Scattered pages on related topics (one in "Deploy", one in "Configuration", one in "Advanced") look less authoritative.

When revising IA, consider the SEO cost of moving pages between sections — URL changes need redirects. Don't churn the IA for aesthetic reasons.

Common IA mistakes

Related

• Navigation configuration — the config reference for the sidebar

• Content types — Diátaxis affects where pages go

• Linking — cross-links complement IA

• SEO for docs — topical clusters as ranking signal

• Understand your audience — persona research informs IA decisions