---
title: "When to Use Auto-Generation"
description: "Discover scenarios where auto-generation is ideal for your documentation"
---

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

```typescript
{
    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:**

```typescript
{
    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

```typescript
{
    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

```typescript
{
    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

```typescript
{
    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:

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

**Result:**

1. Overview (manual, position 1)
2. Quick Start (manual, position 2)
3. Advanced (auto, alphabetical)
4. Caching (auto, alphabetical)
5. Deployment (auto, alphabetical)

See [Hybrid Approach](/docs/generation-strategies/hybrid-approach/best-of-both) 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:

```typescript
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:

- [Auto-Generation Examples](/docs/generation-strategies/auto-generation/examples)
- [Manual Creation](/docs/generation-strategies/manual-creation/explicit-control)
- [Hybrid Approach](/docs/generation-strategies/hybrid-approach/best-of-both)