--- title: "Nested Setup Best Practices" description: "Learn proven patterns for organizing nested groups effectively" --- Nesting groups gives power, but structure matters. Here are best practices to keep your documentation organized and maintainable. ## Organization Principles ### 1. Limit Nesting Depth ``` ✅ Good: 3-4 levels max Home > Docs > Getting Started > Installation Home > Docs > Features > Authentication > OAuth ❌ Too deep: 6+ levels Home > Docs > Features > Core > Auth > Providers > OAuth > Config ``` **Rule:** If you need more than 4 levels, consider a separate collection instead. ### 2. Consistent Folder Structure **Pattern:** Folder hierarchy exactly matches navigation configuration. ```typescript // Configuration groups: [ { id: "core", label: "Core", groups: [ { id: "auth", label: "Auth", autoGenerated: true }, { id: "data", label: "Data", autoGenerated: true }, ], }, ] // File system (must match) content/docs/ ├─ core/ │ ├─ auth/ <- matches config │ │ ├─ overview.md │ │ └─ setup.md │ └─ data/ <- matches config │ ├─ overview.md │ └─ schemas.md ``` Never create folders that don't match your config, or vice versa. ### 3. Use Meaningful Names Group IDs should be: - **Short:** 2-3 words max - **Descriptive:** Clear what they contain - **URL-friendly:** No spaces, use hyphens ``` ✅ auth, data-models, webhooks, api-reference ❌ auth-and-authorization, user-management-system, very-detailed-api-docs ``` Labels (visible to users) can be longer: ```typescript { id: "auth", label: "Authentication & Authorization" } { id: "data-models", label: "Data Models & Schemas" } { id: "webhooks", label: "Webhooks & Events" } ``` ### 4. Mix Auto and Manual Strategically **Use auto-generation for:** - Stable content that grows organically - Categories that frequently get new pages - User-generated or plugin content **Use manual entries for:** - Fixed sequences (setup steps) - Curated collections - External links - Selective display ```typescript // Good: Auto for optional features, manual for required setup groups: [ { id: "getting-started", label: "Getting Started", autoGenerated: false, // Manual: specific order matters entries: [ { slug: "setup/requirements" }, { slug: "setup/installation" }, { slug: "setup/configuration" }, ], }, { id: "plugins", label: "Plugins", autoGenerated: true, // Auto: add new plugin docs anytime }, ]; ``` ### 5. Organize by User Journey Group structure should match how users navigate the product: ``` ✅ Task-based ├─ Getting Started ├─ Core Features ├─ Advanced Configuration ├─ Troubleshooting ❌ Random order ├─ API Reference ├─ Setup ├─ Examples ├─ Architecture ``` Users progress through sections naturally. No backtracking. ## Navigation Patterns ### Pattern 1: Feature-Based (Most Common) ``` Products ├─ Product A │ ├─ Installation │ ├─ Configuration │ ├─ How-To Guides │ └─ API Reference ├─ Product B │ └─ [same structure] └─ Product C └─ [same structure] ``` **Use when:** - Multi-product platform - Each product has independent docs - Users work with specific product ### Pattern 2: Audience-Based ``` Documentation ├─ For Users │ ├─ Getting Started │ ├─ How-To Guides │ └─ FAQ ├─ For Developers │ ├─ API Reference │ ├─ SDK Guides │ └─ Examples └─ For Operators ├─ Installation ├─ Configuration └─ Troubleshooting ``` **Use when:** - Different docs for different user types - Audiences have different needs - Clear separation of concerns ### Pattern 3: Technical Layers ``` Platform ├─ Frontend │ ├─ Components │ ├─ Styling │ └─ State Management ├─ Backend │ ├─ API │ ├─ Database │ └─ Authentication └─ DevOps ├─ Deployment ├─ Monitoring └─ Scaling ``` **Use when:** - Technical documentation - Multiple teams (frontend, backend, ops) - Clear technical boundaries ### Pattern 4: By Complexity ``` Learning Path ├─ Fundamentals │ ├─ What is X │ ├─ Why use X │ └─ Getting Started ├─ Intermediate │ ├─ Core Concepts │ ├─ Practical Examples │ └─ Debugging └─ Advanced ├─ Architecture ├─ Performance Tuning └─ Internals ``` **Use when:** - Content has skill progression - Want to guide users from beginner -> advanced - Different sections for different expertise levels ## Common Mistakes to Avoid ### Mistake 1: Over-Nesting ``` ❌ Too deep Home > Docs > Features > Core > Settings > Advanced > Config > Database > Setup ``` **Fix:** Keep max 4 levels. Use tabs or separate collections for different concerns. ### Mistake 2: Inconsistent Structure ``` ❌ Mismatches Config says: groups.auth.groups.oauth Folder has: auth/providers/oauth/ Auto-gen fails! ``` **Fix:** Folder structure must exactly match configuration. ### Mistake 3: Unclear Group Names ``` ❌ Vague ├─ Category A ├─ Category B ├─ Group 1 └─ Other Stuff ``` **Fix:** Use descriptive names that explain content. ### Mistake 4: Mixing Organizational Schemes ``` ❌ Inconsistent ├─ Getting Started (by user journey) ├─ Backend (by layer) ├─ Payment Processing (by feature) └─ For Developers (by audience) ``` **Fix:** Pick one organizing principle and stick with it. ### Mistake 5: Auto-Gen in Strict Order ``` ❌ Doesn't work Config requires specific order: 1. Prerequisites 2. Installation 3. Configuration But auto-gen alphabetizes: 1. Configuration 2. Installation 3. Prerequisites ``` **Fix:** Use manual entries when order matters. ## Maintenance Best Practices ### Keep Configuration DRY ```typescript // ❌ Repetitive groups: [ { id: "docs", label: "Documentation", groups: [ { id: "intro", label: "Introduction", autoGenerated: true }, { id: "setup", label: "Setup", autoGenerated: true }, { id: "guide", label: "Guide", autoGenerated: true }, ], }, ]; // ✅ Use helpers const createAutoGroup = (id, label) => ({ id, label, autoGenerated: true }); groups: [ { id: "docs", label: "Documentation", groups: [ createAutoGroup("intro", "Introduction"), createAutoGroup("setup", "Setup"), createAutoGroup("guide", "Guide"), ], }, ]; ``` ### Document Your Organization Add a README in content/: ``` # Documentation Structure ## Getting Started - Prerequisites, installation, first project - Order: Manual (sequence matters) ## Features - Feature-specific guides - Order: Auto-generated (alphabetical) ## API Reference - Endpoint documentation - Order: Manual (grouped by resource) ## Advanced - Performance, security, internals - Order: Auto-generated ``` ### Plan Before Building ``` Step 1: Sketch on paper ├─ Top-level sections (tabs) ├─ Main groups ├─ Subgroups └─ Number of pages per section Step 2: Create folder structure mkdir -p content/docs/section/subsection Step 3: Write configuration Add to data/config.ts Step 4: Create content files Add .md files to folders Step 5: Test in dev server Verify navigation matches intent ``` ## Scaling Guidelines | Documentation Size | Recommended Structure | Max Depth | | ------------------ | -------------------------------- | --------- | | < 20 pages | Single level or no nesting | 2 | | 20-50 pages | Single-level nesting | 2-3 | | 50-150 pages | Single/multi-level nesting | 3-4 | | 150+ pages | Multiple collections recommended | - | As docs grow, consider splitting into separate collections rather than deeper nesting. ## Real-World Example **Company:** SaaS platform with 3 products **Users:** End users, developers, operators **Content:** 200+ pages **Structure:** ```typescript export const SIDEBAR_NAVIGATION = { // Collection 1: User docs "user-docs": { defaultTab: { label: "Getting Started", icon: "🚀" }, groups: [ { id: "basics", label: "Basics", groups: [ { id: "setup", label: "Setup", autoGenerated: true }, { id: "first-steps", label: "First Steps", autoGenerated: true }, ], }, { id: "products", label: "Products", groups: [ { id: "product-a", label: "Product A", autoGenerated: true }, { id: "product-b", label: "Product B", autoGenerated: true }, { id: "product-c", label: "Product C", autoGenerated: true }, ], }, ], }, // Collection 2: Developer docs "dev-docs": { defaultTab: { label: "Getting Started", icon: "🔧" }, groups: [ { id: "api", label: "API Reference", autoGenerated: true }, { id: "sdks", label: "SDKs", autoGenerated: true }, { id: "webhooks", label: "Webhooks", autoGenerated: true }, ], }, // Collection 3: Operations "ops-docs": { defaultTab: { label: "Setup", icon: "⚙️" }, groups: [ { id: "setup", label: "Setup", autoGenerated: false, entries: [...] }, { id: "monitoring", label: "Monitoring", autoGenerated: true }, { id: "scaling", label: "Scaling", autoGenerated: true }, ], }, }; ``` **Result:** - 3 separate collections (not deeply nested) - Each serves different audience - Each can be maintained independently - Clear organization at all levels - Maximum 3 levels deep: cleanest UX ## Next Steps - [Single-Level Nesting](/docs/configuration/advanced/nested-setup/single-level) - [Multi-Level Nesting](/docs/configuration/advanced/nested-setup/multi-level) - [Tab Management](/docs/configuration/advanced/tab-management/creating-tabs)