--- title: "Multi-Level Nesting" description: "Discover how to create deeply nested group hierarchies for complex documentation structures" --- 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 ```typescript 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.md ``` ## Resulting 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 > Stripe ``` Users 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 Practices ``` ## Navigation 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 • Analytics ``` Users expand sections to explore. Collapses keep sidebar clean. ## Auto-Generation at Each Level ```typescript { 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 Started ``` Keep 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 nesting ``` ## Migration 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.md ``` Configuration grows with folders. No migration needed—just add nesting as content grows. ## Next Steps - [Single-Level Nesting](/docs/configuration/advanced/nested-setup/single-level) - [Nesting Best Practices](/docs/configuration/advanced/nested-setup/best-practices) - [Real-World Examples](/docs/navigation-system/hierarchy/real-world-examples)