Hybrid Generation Flexibility

The hybrid approach (manual entries + auto-generation) is one of CelestialDocs’ 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

CelestialDocs Solution: Hybrid

Pin important pages manually, rest auto-discover:

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

Result:

Overview (guaranteed position)
Quick Start (guaranteed position)
Advanced Setup (auto, alphabetical)
Best Practices (auto)
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

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

Month 3: 15 pages, manual becomes tedious

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:

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	❌	✅	❌
CelestialDocs	✅	✅	✅

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

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

Auto-Generation (manual)
Manual Creation (manual)
Hybrid Approach (auto-discovered - this site!)
Any future strategies (auto-discovered)

Next: Learn other selling points:

Search Documentation