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