When to Use Auto-Generation

Auto-generation is powerful, but it’s not always the right choice. Here’s when and why to use it.

Ideal Scenarios

1. Growing Documentation

Your docs are expanding and new pages appear frequently.

Example:

Initial setup: 20 pages
Scenario: Team adds 5 new pages per week
Problem: Manual config becomes maintenance burden
Solution: Auto-generation discovers pages automatically

Configuration:

{
    id: "guides",
    label: "Guides",
    autoGenerated: true,
}

Result: New files appear automatically every week, zero manual updates.

2. Large Documentation (100+ pages)

Too many pages to manually list.

Example: API documentation with 50+ endpoints

content/api/
├── endpoints/
│   ├── users/
│   │   ├── get.md
│   │   ├── create.md
│   │   ├── update.md
│   │   └── delete.md
│   ├── posts/
│   │   ├── get.md
│   │   ├── create.md
│   │   └── update.md
│   ... (20+ more endpoints)

Configuration:

{
    id: "endpoints",
    label: "Endpoints",
    autoGenerated: true,
}

Result: 50+ pages appear automatically, no manual list needed.

3. Alphabetical Ordering is Acceptable

Your content works well alphabetically.

Good:

API endpoints (A-Z order is fine)
Feature list (Users don’t care about order)
Troubleshooting topics (Searchable anyway)
Reference documentation

Not good:

Tutorials (Need specific progression)
Getting started (Must start with basics)
Conceptual guides (Build on each other)

4. Multiple Contributors

Team members add content independently.

Scenario:

Alice adds authentication.md
Bob adds caching.md
Charlie adds deployment.md
Nobody updates config file

With auto-generation: All three appear automatically, conflict-free.

With manual entries: Whoever updates last wins; others’ files get lost.

Scenarios to Avoid Auto-Generation

1. Specific Ordering Required

Alphabetical doesn’t match your content flow.

Example: Tutorial series

Lessons must appear in order:
1. Introduction
2. Installation
3. First Application
4. Advanced Topics
5. Troubleshooting

Alphabetical order would be:
1. Advanced Topics ❌
2. First Application ❌
3. Installation ✓
4. Introduction ❌
5. Troubleshooting ✓

Solution: Use manual configuration

{
    id: "tutorial",
    label: "Tutorial",
    entries: [
        { slug: "tutorial/introduction" },
        { slug: "tutorial/installation" },
        { slug: "tutorial/first-app" },
        { slug: "tutorial/advanced" },
        { slug: "tutorial/troubleshooting" },
    ],
}

2. Carefully Curated Selection

You only want certain files in navigation.

Example: Drafts exist in folder but shouldn’t show

content/guides/
├── published/
│   ├── getting-started.md  <- Should appear
│   ├── setup.md            <- Should appear
├── drafts/
│   ├── wip-new-feature.md  <- Shouldn't appear
│   └── coming-soon.md      <- Shouldn't appear

Solution: Manual configuration

{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/published/getting-started" },
        { slug: "guides/published/setup" },
    ],
}

3. Custom Labels Throughout

Every file needs different navigation label than file name.

Example:

Files:
- api-reference.md        (label: "API Reference") ✓
- sdk-examples.md         (label: "SDK Examples") ✓
- faq-common-issues.md    (label: "FAQ") ✗ auto-gen would show "Faq Common Issues"
- troubleshooting.md      (label: "Errors & Fixes") ✗
- performance-tuning.md   (label: "Optimization") ✗

Solution: Manual configuration for custom labels

{
    id: "help",
    label: "Help",
    entries: [
        { slug: "help/api-reference" },
        { slug: "help/faq-common-issues", label: "FAQ" },
        { slug: "help/troubleshooting", label: "Errors & Fixes" },
        { slug: "help/performance-tuning", label: "Optimization" },
    ],
}

4. Different Audiences

Different documents for different user types.

Example: Developer docs repo

content/
├── user-guide/
│   ├── getting-started.md
│   ├── faq.md
│   └── support.md
├── developer-guide/
│   ├── architecture.md
│   ├── contributing.md
│   └── build-setup.md
├── internal/
│   ├── roadmap.md
│   ├── meeting-notes.md
│   └── TODO.md  <- Should NOT appear publicly

Problem: Auto-gen on root would show internal docs

Solution: Manual config or use navHidden: true

Hybrid: The Best of Both

Want auto-discovery + specific ordering?

Use hybrid mode:

{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/overview" },      // Always first
        { slug: "guides/quick-start" },   // Always second
    ],
    autoGenerated: true,  // Rest auto-discovered
}

Result:

Overview (manual, position 1)
Quick Start (manual, position 2)
Advanced (auto, alphabetical)
Caching (auto, alphabetical)
Deployment (auto, alphabetical)

See Hybrid Approach for details.

Decision Matrix

Scenario	Auto-Gen	Manual	Hybrid
Growing docs	✅	❌	✅
Large docs	✅	❌	✅
Alphabetical OK	✅	❌	✅
Multiple contributors	✅	❌	✅
Specific order needed	❌	✅	✅
Curated selection	❌	✅	✅
Custom labels	❌	✅	✅
Mixed requirements	❌	❌	✅

Real-World Pattern

Smart teams use all three:

groups: [
    // Auto-generated: High-volume auto-discovering sections
    { id: "features", label: "Features", autoGenerated: true },
    { id: "faq", label: "FAQ", autoGenerated: true },

    // Manual: Carefully structured progressive learning
    {
        id: "getting-started",
        label: "Getting Started",
        entries: [
            { slug: "getting-started/intro" },
            { slug: "getting-started/install" },
            { slug: "getting-started/first-app" },
        ],
    },

    // Hybrid: Best of both
    {
        id: "guides",
        label: "Guides",
        entries: [{ slug: "guides/overview" }],
        autoGenerated: true,
    },
];

Next Steps

Learn about:

Search Documentation