Manual Creation & Explicit Control

Manual configuration gives you complete control over navigation structure, ordering, and presentation.

What is Manual Creation?

Manually list every entry you want in navigation:

{
    id: "getting-started",
    label: "Getting Started",
    entries: [
        { slug: "getting-started/introduction" },
        { slug: "getting-started/installation" },
        { slug: "getting-started/quick-start" },
    ],
}

Key differences from auto-generation:

• No folder scanning
• You control exact order
• You control which files appear
• No autoGenerated: true

Basic Manual Configuration

{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/overview" },
        { slug: "guides/setup" },
        { slug: "guides/advanced" },
    ],
}

Entry Customization

Basic Entry

{
    slug: "guides/installation";
}

Override Label

{
    slug: "guides/very-long-file-name",
    label: "Short Name",  // Shows in sidebar
}

Add Icon

{
    slug: "guides/installation",
    icon: "⚡",
}

Full Customization

{
    slug: "guides/installation",
    label: "Get Started",
    icon: "🚀",
}

Real-World Example: Tutorial

Tutorials need specific order. Auto-generation would fail (alphabetical order wouldn’t match teaching progression).

Setup

{
    id: "tutorials",
    label: "Tutorials",
    entries: [
        { slug: "tutorials/01-introduction", label: "Introduction" },
        { slug: "tutorials/02-installation", label: "Installation" },
        { slug: "tutorials/03-hello-world", label: "Hello World" },
        { slug: "tutorials/04-variables", label: "Variables" },
        { slug: "tutorials/05-functions", label: "Functions" },
        { slug: "tutorials/06-modules", label: "Modules" },
        { slug: "tutorials/07-conclusion", label: "Wrap-Up" },
    ],
}

Result

🎓 Tutorials
├── Introduction
├── Installation
├── Hello World
├── Variables
├── Functions
├── Modules
└── Wrap-Up

Why manual? Alphabetical would be wrong (01-intro, 02-install, etc.)

Example: Curated Feature Selection

Show only popular features, hide others:

Files

content/features/
├── authentication.md ✓
├── breadcrumbs.md ✓
├── dark-mode.md ✓
├── experimental-beta.md ✗
├── icons.md ✓
├── internal-test.md ✗
└── theme.md ✓

Setup

{
    id: "features",
    label: "Features",
    entries: [
        { slug: "features/authentication" },
        { slug: "features/breadcrumbs" },
        { slug: "features/dark-mode" },
        { slug: "features/icons" },
        { slug: "features/theme" },
    ],
}

Result

✨ Features
├── Authentication
├── Breadcrumbs
├── Dark Mode
├── Icons
└── Theme
(Experimental and internal tests hidden)

Example: Custom Navigation Hierarchy

Reorganize files into different structure than file system:

Files

content/docs/
├── installation.md
├── setup.md
├── authentication.md
└── performance.md

Configuration (Different Order + Custom Labels)

{
    id: "getting-started",
    label: "Getting Started",
    entries: [
        { slug: "getting-started/installation", label: "Install" },
        { slug: "getting-started/setup", label: "Initial Setup" },
    ],
},
{
    id: "advanced",
    label: "Advanced",
    entries: [
        { slug: "getting-started/authentication", label: "Authentication & Security" },
        { slug: "getting-started/performance", label: "Performance Tuning" },
    ],
}

Result

🚀 Getting Started
├── Install
└── Initial Setup

🎓 Advanced
├── Authentication & Security
└── Performance Tuning

Example: Multi-Version API Docs

Support multiple API versions manually:

{
    id: "api-v1",
    label: "v1 (Deprecated)",
    entries: [
        { slug: "api/v1/endpoints" },
        { slug: "api/v1/authentication" },
        { slug: "api/v1/errors" },
    ],
},
{
    id: "api-v2",
    label: "v2 (Current)",
    entries: [
        { slug: "api/v2/getting-started" },
        { slug: "api/v2/endpoints" },
        { slug: "api/v2/authentication" },
        { slug: "api/v2/webhooks" },
        { slug: "api/v2/errors" },
    ],
},
{
    id: "api-v3",
    label: "v3 (Beta)",
    entries: [
        { slug: "api/v3/overview" },
        { slug: "api/v3/breaking-changes" },
    ],
}

Result

v1 (Deprecated)
├── Endpoints
├── Authentication
└── Errors

v2 (Current)
├── Getting Started
├── Endpoints
├── Authentication
├── Webhooks
└── Errors

v3 (Beta)
├── Overview
└── Breaking Changes

When Manual is Better

✅ Use manual when:

• Specific order is critical (tutorials, progressive learning)
• Careful curation needed (hide some files)
• Custom labels throughout
• Multi-version documentation
• Small documentation (easy to maintain)
• Static content (doesn’t grow frequently)

❌ Not ideal when:

• Documentation grows rapidly
• Many pages (becomes tedious)
• Multiple contributors (merge conflicts)
• Alphabetical order acceptable

Advantages

✅ Complete control - Every aspect configurable ✅ Clear intent - Config shows exactly what appears ✅ Version management - Easy to hide old versions ✅ Curation - Show only what’s ready ✅ Custom ordering - Any order you want ✅ Small documentation - Trivial to maintain

Disadvantages

❌ Maintenance burden - Update config when adding files ❌ Scaling issues - Becomes tedious with 100+ pages ❌ Easy to miss - Forget to add new files ❌ Merge conflicts - Multiple people editing same file ❌ No discovery - New files invisible until listed

Hybrid: Get Both

Want manual ordering + auto-discovery?

{
    id: "guides",
    label: "Guides",
    entries: [
        { slug: "guides/overview", label: "📋 Overview" },
        { slug: "guides/getting-started", label: "🚀 Getting Started" },
    ],
    autoGenerated: true,  // Rest auto-discovered
}

See Hybrid Approach for details.

Next Steps

Learn about:

• Hybrid Approach
• Configuration Examples
• Auto-Generation