Nested Setup Best Practices

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.

// 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:

{ 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

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

// ❌ 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

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:

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
• Multi-Level Nesting
• Tab Management