Search Documentation

Search for pages and headings in the documentation

Hybrid Approach: Best of Both Worlds

The hybrid approach is a game-changer. Pin important entries first, then auto-discover the rest. Get convenience without sacrificing control.

What is the Hybrid Approach?

Combine entries (manual) + autoGenerated: true (auto-discovery):

{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/overview" },        // Manual: Always first
        { slug: "guides/getting-started" }, // Manual: Always second
    ],
    autoGenerated: true,  // Auto-discover rest
}

Result:

  1. Overview (manual, position 1)
  2. Getting Started (manual, position 2)
  3. Advanced… (auto, alphabetical)
  4. Caching… (auto, alphabetical)
  5. Deployment… (auto, alphabetical)

The Problem It Solves

Manual only: New pages require config update

// Without hybrid, need to edit config for each new page
entries: [
    { slug: "guides/overview" },
    { slug: "guides/getting-started" },
    { slug: "guides/advanced-setup" }, // <- New file, must add here
    { slug: "guides/troubleshooting" }, // <- New file, must add here
];

Auto-gen only: Can’t control order

// Auto-generation is alphabetical, can't pin important pages first
{
    autoGenerated: true;
}
// Result: Advanced (1st), Getting Started (2nd), Overview (3rd) ❌

Hybrid: Best of both

{
    entries: [
        { slug: "guides/overview" },      // Always first
        { slug: "guides/getting-started" }, // Always second
    ],
    autoGenerated: true,  // New pages appear automatically
}
// Result: Overview (1), Getting Started (2), Advanced (3), Caching (4)... ✅

Example 1: Documentation Hub

Scenario

You have a growing documentation site. Important overview always first, rest auto-discovered.

Setup

{
    id: "documentation",
    label: "Documentation",
    entries: [
        {
            slug: "documentation/overview",
            label: "📚 Overview",
            icon: "📖"
        },
        {
            slug: "documentation/getting-started",
            label: "🚀 Quick Start",
            icon: "⚡"
        },
    ],
    autoGenerated: true,
}

File Structure

content/docs/documentation/
├── overview.md
├── getting-started.md
├── advanced-setup.md      (auto)
├── caching-strategies.md  (auto)
├── deployment-guide.md    (auto)
└── faq.md                 (auto)

Result

📚 Documentation
├── 📖 Overview              (manual)
├── ⚡ Quick Start           (manual)
├── Advanced Setup           (auto, alphabetical)
├── Caching Strategies       (auto)
├── Deployment Guide         (auto)
└── FAQ                      (auto)

Key: User sees important pages first, but new content appears automatically!

Example 2: Growing Feature List

Scenario

API with many endpoints. Show popular endpoints manually, rest auto-discovered.

Setup

{
    id: "endpoints",
    label: "Endpoints",
    entries: [
        { slug: "api/endpoints/authentication", label: "🔐 Authentication" },
        { slug: "api/endpoints/users", label: "👥 Users" },
        { slug: "api/endpoints/posts", label: "📝 Posts" },
    ],
    autoGenerated: true,  // Other endpoints auto-discovered
}

File Structure

content/api/endpoints/
├── authentication.md  (manual)
├── users.md          (manual)
├── posts.md          (manual)
├── comments.md       (auto)
├── notifications.md  (auto)
└── webhooks.md       (auto)

Result

📡 Endpoints
├── 🔐 Authentication  (manual)
├── 👥 Users          (manual)
├── 📝 Posts          (manual)
├── Comments          (auto)
├── Notifications     (auto)
└── Webhooks          (auto)

Key: Popular endpoints highlighted at top, new endpoints appear automatically!

Example 3: Tutorial + Reference

Scenario

Tutorial series (order matters) + growing reference section (alphabetical OK).

Setup

{
    id: "learning",
    label: "Learning Guide",
    entries: [
        // Tutorial chapters - order matters!
        { slug: "learning/01-intro", label: "Introduction" },
        { slug: "learning/02-setup", label: "Setup" },
        { slug: "learning/03-hello-world", label: "Hello World" },
        { slug: "learning/04-variables", label: "Variables" },
        { slug: "learning/05-functions", label: "Functions" },
    ],
    autoGenerated: true,  // Reference pages discovered automatically
}

File Structure

content/learning/
├── 01-intro.md          (manual, chap 1)
├── 02-setup.md          (manual, chap 2)
├── 03-hello-world.md    (manual, chap 3)
├── 04-variables.md      (manual, chap 4)
├── 05-functions.md      (manual, chap 5)
├── api-reference.md     (auto)
├── best-practices.md    (auto)
└── common-patterns.md   (auto)

Result

🎓 Learning Guide
├── Introduction         (manual)
├── Setup               (manual)
├── Hello World         (manual)
├── Variables           (manual)
├── Functions           (manual)
├── Api Reference       (auto)
├── Best Practices      (auto)
└── Common Patterns     (auto)

Key: Tutorial flows logically, reference grows without intervention!

Example 4: Scaling Over Time

Month 1 (Initial Setup)

{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/overview" },
        { slug: "guides/quick-start" },
    ],
    autoGenerated: true,
}

Files: overview.md, quick-start.md

Result:

Guides
├── Overview
└── Quick Start

Month 3 (Growing)

// No config change!
{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/overview" },
        { slug: "guides/quick-start" },
    ],
    autoGenerated: true,
}

Files:

├── overview.md
├── quick-start.md
├── advanced-setup.md
├── caching.md
└── deployment.md

Result:

Guides
├── Overview         (manual)
├── Quick Start      (manual)
├── Advanced Setup   (auto)
├── Caching         (auto)
└── Deployment      (auto)

Month 6 (Mature)

// Still no config change!
{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/overview" },
        { slug: "guides/quick-start" },
    ],
    autoGenerated: true,
}

Files: 15+ files

Result:

Guides
├── Overview         (manual)
├── Quick Start      (manual)
├── Advanced...
├── Architecture...
├── API Reference...
├── Best Practices...
├── Caching...
├── Deployment...
├── Docker Setup...
├── Error Handling...
├── FAQ...
├── Performance...
├── Security...
├── Testing...
└── Troubleshooting...

Key: Same config, but docs grew 15x!

Implementation Steps

1. Identify Key Pages

Which pages should always appear first?

Example: “Overview and Quick Start are essential”

2. Add Manual Entries

entries: [
    { slug: "guides/overview" },
    { slug: "guides/quick-start" },
],

3. Enable Auto-Generation

autoGenerated: true,

4. Organize Files

Put manual pages in folder, rest will auto-discover.

How It Works Internally

  1. Process manual entries first - Add in order specified
  2. Track which slugs are already listed - Avoid duplicates
  3. Scan folder for all files - Find additional files
  4. Filter out already-listed - Exclude manual entries from auto-discovery
  5. Sort remainder alphabetically - Append in sorted order
  6. Combine - Manual first, then auto-discovered

Best Practices

1. Use for Essential Guides

entries: [
    { slug: "guides/getting-started" },     // Always first
    { slug: "guides/core-concepts" },       // Always second
],
autoGenerated: true,

2. Avoid Duplication

// DON'T: List something in entries AND have autoGenerated
// The system handles duplicates, but it's clearer if you don't

entries: [
    { slug: "guides/overview" },  // Manual
],
autoGenerated: true,  // Rest auto-discovered (excludes overview)

3. Combine with Icons

entries: [
    { slug: "guides/overview", icon: "📋", label: "Overview" },
    { slug: "guides/quick-start", icon: "🚀", label: "Quick Start" },
],
autoGenerated: true,

4. Use for Navigation Hinting

entries: [
    // Suggest the two best starting points
    { slug: "docs/getting-started" },
    { slug: "docs/first-project" },
],
autoGenerated: true,  // Everything else is fair game

Limitations

  • Manual entries must exist in file system
  • Duplicates are handled (but wasteful to list twice)
  • Alphabetical ordering used for auto-discovered files (can’t customize)

When to Use Hybrid

✅ Perfect for:

  • Growing documentation
  • Pin important pages + expand
  • Tutorial + reference mix
  • Multiple audiences (pin first useful page)
  • Learning guides (structured start + reference)

❌ Not ideal for:

  • All pages need custom ordering
  • Very small docs (just use manual)
  • Very large docs with no clear priorities

Next Steps

Learn more: