Multi-Level Nesting
Multi-level nesting means groups nested 3+ levels deep. Use this when your documentation has complex hierarchies.
Deep Nesting Structure
Level 0 (Root)
└── Level 1 Group
└── Level 2 Subgroup
└── Level 3 Subsubgroup
└── Entries (Pages)Depth: 4 levels from root to pages. Can be even deeper.
Configuration Example
export const SIDEBAR_NAVIGATION = {
platform: {
defaultTab: { label: "Platform", icon: "🚀" },
groups: [
{
id: "platform-suite",
label: "Platform Suite",
groups: [
{
id: "core-services",
label: "Core Services",
groups: [
{
id: "authentication",
label: "Authentication",
groups: [
{
id: "oauth",
label: "OAuth 2.0",
autoGenerated: true,
},
{
id: "saml",
label: "SAML",
autoGenerated: true,
},
],
},
{
id: "data-storage",
label: "Data Storage",
groups: [
{
id: "databases",
label: "Databases",
autoGenerated: true,
},
{
id: "caching",
label: "Caching",
autoGenerated: true,
},
],
},
],
},
{
id: "integrations",
label: "Integrations",
groups: [
{
id: "third-party",
label: "Third-Party Services",
groups: [
{
id: "payments",
label: "Payment Processors",
autoGenerated: true,
},
{
id: "analytics",
label: "Analytics Providers",
autoGenerated: true,
},
],
},
],
},
],
},
],
},
};Depth: 6 levels from root to pages.
File Organization for Deep Nesting
Folder structure mirrors navigation depth:
content/platform/
└── platform-suite/ <- Level 1
├── core-services/ <- Level 2
│ ├── authentication/ <- Level 3
│ │ ├── oauth/ <- Level 4
│ │ │ ├── getting-started.md
│ │ │ ├── setup.md
│ │ │ ├── troubleshooting.md
│ │ │ └── examples.md
│ │ └── saml/ <- Level 4
│ │ ├── overview.md
│ │ ├── integration.md
│ │ └── federation.md
│ └── data-storage/ <- Level 3
│ ├── databases/ <- Level 4
│ │ ├── postgresql.md
│ │ ├── mongodb.md
│ │ └── performance.md
│ └── caching/ <- Level 4
│ ├── redis.md
│ ├── memcached.md
│ └── strategies.md
└── integrations/ <- Level 2
└── third-party/ <- Level 3
├── payments/ <- Level 4
│ ├── stripe.md
│ ├── paypal.md
│ └── webhook-handling.md
└── analytics/ <- Level 4
├── google-analytics.md
├── mixpanel.md
└── event-tracking.mdResulting Breadcrumbs
Navigation paths get long but clear:
Home > Platform > Core Services > Authentication > OAuth > Getting Started
Home > Platform > Core Services > Data Storage > Databases > PostgreSQL
Home > Platform > Integrations > Third-Party > Payments > StripeUsers understand exactly where they are.
When to Use Multi-Level Nesting
Good use cases:
- Enterprise software with many subsystems
- Complex APIs with multiple service tiers
- Large platforms with distinct areas
- Organizations with clear hierarchical structure
Examples:
🏢 Enterprise Platform
├─ Account Management
│ ├─ User Management
│ │ ├─ SAML
│ │ ├─ OAuth
│ │ └─ LDAP
│ ├─ Organization
│ │ ├─ Teams
│ │ ├─ Permissions
│ │ └─ Roles
│ └─ Billing
│ ├─ Subscriptions
│ ├─ Invoices
│ └─ Payments
└─ Integrations
├─ Marketplace
│ ├─ Discovery
│ ├─ Installation
│ └─ Publishing
└─ Webhooks
├─ Setup
├─ Events
└─ Best PracticesNavigation Sidebar Experience
Deep nesting creates collapsible sections:
▼ Platform Suite
▼ Core Services
▼ Authentication (Current Section)
▼ OAuth
• Getting Started (Current Page)
• Setup
• Troubleshooting
• Examples
• SAML
▼ Data Storage
• Databases
• Caching
▼ Integrations
▼ Third-Party
• Payments
• AnalyticsUsers expand sections to explore. Collapses keep sidebar clean.
Auto-Generation at Each Level
{
id: "services",
label: "Services",
groups: [
{
id: "core",
label: "Core",
autoGenerated: false, // Manual control
groups: [
{
id: "auth",
label: "Authentication",
autoGenerated: true, // Auto-discover all files
groups: [
{
id: "methods",
label: "Methods",
autoGenerated: true, // Auto-discover all files in subdirs
},
],
},
],
},
],
}Flexible mixing:
- Some levels auto-generated
- Some levels manual
- Choose per level what makes sense
Files in services/core/auth/methods/ appear automatically under Methods subgroup.
Performance Considerations
Deep nesting affects:
Navigation rendering: More levels = more DOM nodes = slight performance cost User experience: Too many clicks to reach content
Recommendations:
- Maximum 4-5 levels before getting cumbersome
- Beyond 5 levels, consider redesign
- Use tabs to split into 2-3 collections instead
Width Constraints
Deeply nested labels can wrap:
Home > Platform Suite > Core Services > Authentication > OAuth > Getting StartedKeep group labels short (2-3 words):
- ✅ “OAuth 2.0” not “OAuth 2.0 Authentication Protocol”
- ✅ “User Mgmt” not “User Management System”
- ✅ “Payments” not “Payment Processing Integration”
Comparison: When to Use What
Simple (No nesting):
❌ 100+ pages in flat list
✅ < 20 pages, simple structure
Single-Level (1 level deep):
✅ 30-100 pages with clear categories
✅ Most documentation
✅ 2-3 organizational layers
Multi-Level (3+ levels deep):
✅ 200+ pages with complex structure
✅ Enterprise software
✅ Clear hierarchical system
❌ Might indicate need for multiple collections
Multiple Collections (separate sites):
✅ Different audiences
✅ Independent teams
✅ Different navigation styles
✅ Instead of extremely deep nestingMigration Path
Starting simple and growing deep:
Step 1: Start flat
docs/
├─ intro.md
├─ setup.md
├─ guide.md
Step 2: Add single-level
docs/
├─ getting-started/
│ ├─ intro.md
│ └─ setup.md
└─ guides/
└─ guide.md
Step 3: Add multi-level
docs/
├─ getting-started/
│ ├─ quick/
│ │ ├─ intro.md
│ │ └─ setup.md
│ └─ detailed/
│ ├─ prerequisites.md
│ └─ configuration.md
└─ guides/
├─ basic/
│ └─ guide.md
└─ advanced/
└─ guide.mdConfiguration grows with folders. No migration needed—just add nesting as content grows.