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.