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: