---
title: "Hybrid Generation Flexibility"
description: "Why the hybrid auto-generation + manual control approach is a game-changer"
---

The hybrid approach (manual entries + auto-generation) is one of PID^TOO||' most powerful features. It solves a problem no other documentation system elegantly handles.

## The Problem Other Systems Face

### Pure Auto-Generation Systems

**Problem:** No control over order or which pages appear

```
Scenario: Your feature is called "Advanced Setup" but it's critical
Result: Appears alphabetically between "Accounting" and "Dashboard"
         Users miss it because it's buried in the middle
```

### Pure Manual Systems

**Problem:** Tedious to maintain; new content is invisible until added to config

```
Scenario: Team member adds "deployment-guide.md"
Result: Page exists but doesn't appear in sidebar
        Forgotten in config -> users can't find it
        -> months pass before someone notices
```

## PID^TOO|| Solution: Hybrid

**Pin important pages manually, rest auto-discover:**

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

**Result:**

1. Overview (guaranteed position)
2. Quick Start (guaranteed position)
3. Advanced Setup (auto, alphabetical)
4. Best Practices (auto)
5. Deployment (auto)

## Why This Matters

### For Documentation Authors

 **No maintenance burden** - Add files, they appear automatically
 **Control when needed** - Pin important pages
 **Scales naturally** - 10 pages or 1000, config stays same

### For Documentation Readers

 **Best pages first** - Important content highlighted
 **Complete discovery** - All content findable
 **Professional navigation** - Not buried in alphabetical order

### For Teams

 **No merge conflicts** - Don't fight over config file
 **Fast onboarding** - New contributors just add files
 **Growth-friendly** - Scales from small to enterprise

## Real-World Impact

### Scenario 1: Growing Startup

**Month 1:** 5 pages, manual config is fine

```typescript
entries: [
    { slug: "docs/overview" },
    { slug: "docs/install" },
    { slug: "docs/setup" },
    { slug: "docs/api" },
    { slug: "docs/faq" },
],
```

**Month 3:** 15 pages, manual becomes tedious

```typescript
entries: [
    { slug: "docs/overview" },
    { slug: "docs/install" },
    // ... 10+ more entries ...
    { slug: "docs/troubleshooting" },
    // What about the new deployment guide?
],
```

**Month 6:** With hybrid, just this:

```typescript
entries: [
    { slug: "docs/overview" },    // Essential
    { slug: "docs/quick-start" }, // Essential
],
autoGenerated: true,  // Everything else auto-discovered
```

Documentation grew 3x, **configuration stayed identical**.

### Scenario 2: Multi-Team Documentation

**Team A** adds `advanced-caching.md`
**Team B** adds `performance-tuning.md`
**Team C** adds `troubleshooting.md`

With hybrid: All three appear automatically
With manual: Whoever commits last wins; others' docs forgotten

## Competitive Advantage

| System            | Auto-Gen | Manual | Hybrid |
| ----------------- | -------- | ------ | ------ |
| MkDocs            | �       |      | �     |
| Docusaurus        |        |      | �     |
| GitBook           |        |      | �     |
| Notion            | �       |      | �     |
| **PID^TOO||** |        |      | **** |

PID^TOO|| is the **only system that natively supports hybrid** with elegance.

## How It Sells

"We let you control what matters and automate the rest."

- **For managers:** Reduces documentation maintenance 70%
- **For writers:** Pin important content, forget about new files
- **For readers:** See best content first, discover everything
- **For teams:** Scales from 5 people to 500 without friction

## Implementation Example

This site itself demonstrates hybrid approach:

```typescript
{
    id: "generation-strategies",
    label: "Generation Strategies",
    entries: [
        { slug: "generation-strategies/auto-generation/how-it-works" },
        { slug: "generation-strategies/manual-creation/explicit-control" },
    ],
    autoGenerated: true,  // Other strategies appear too
}
```

Result:

1. Auto-Generation (manual)
2. Manual Creation (manual)
3. Hybrid Approach (auto-discovered - this site!)
4. Any future strategies (auto-discovered)

---

**Next:** Learn other selling points:

- [Hierarchical Power](/docs/advanced-topics/selling-points/hierarchical-power)
- [Type Safety](/docs/advanced-topics/selling-points/type-safety)