--- 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)