Search Documentation

Search for pages and headings in the documentation

Single-Level Nesting

Single-level nesting is when groups contain other groups—but only one layer deep. Perfect for most documentation needs.

Basic Concept

Tab or Root Level
├── Group 1
│   ├── Entry 1
│   ├── Entry 2
│   └── Entry 3
├── Group 2
│   ├── Entry 1
│   └── Entry 2
└── Group 3
    ├── Entry 1
    ├── Entry 2
    ├── Entry 3
    └── Entry 4

Think: Category -> Subcategory -> Pages

Configuration Example

export const SIDEBAR_NAVIGATION = {
    "new-docs": {
        defaultTab: { label: "Overview", icon: "📚" },
        groups: [
            {
                id: "core",
                label: "Core Concepts",
                groups: [
                    // <- Single-level nesting
                    {
                        id: "entries",
                        label: "Understanding Entries",
                        autoGenerated: false,
                        entries: [
                            { slug: "core-concepts/entries/what-are-entries" },
                            { slug: "core-concepts/entries/folder-vs-manual" },
                        ],
                    },
                    {
                        id: "groups",
                        label: "Understanding Groups",
                        autoGenerated: true, // Auto-discover subdirectory
                    },
                ],
            },
            {
                id: "advanced",
                label: "Advanced",
                groups: [
                    // <- Another single-level nesting
                    { id: "performance", label: "Performance", autoGenerated: true },
                    { id: "security", label: "Security", autoGenerated: true },
                ],
            },
        ],
    },
};

Structure:

  • Root: 2 groups (core, advanced)
  • core has 2 subgroups (entries, groups)
  • advanced has 2 subgroups (performance, security)
  • Maximum depth: 2 levels

File Organization Matching

Your folder structure should mirror the navigation:

content/docs/
├── core-concepts/          <- Matches "core" group
│   ├── entries/            <- Matches "entries" subgroup
│   │   ├── what-are-entries.mdx
│   │   └── folder-vs-manual.mdx
│   └── groups/             <- Matches "groups" subgroup
│       ├── basic.mdx
│       ├── nested.mdx
│       └── advanced.mdx
└── advanced/               <- Matches "advanced" group
    ├── performance/        <- Matches "performance" subgroup
    │   ├── optimization.mdx
    │   └── benchmarking.mdx
    └── security/           <- Matches "security" subgroup
        ├── best-practices.mdx
        └── vulnerabilities.mdx

Users see clear navigation path:

Home > Docs > Core Concepts > Entries > What are Entries
Home > Docs > Advanced > Performance > Optimization
Home > Docs > Advanced > Security > Best Practices

Clear hierarchy. Not too deep.

Auto-Generation with Single Nesting

{
    id: "guides",
    label: "How-To Guides",
    groups: [
        {
            id: "getting-started",
            label: "Getting Started",
            autoGenerated: true,  // Auto-discover all files in guides/getting-started/
        },
        {
            id: "advanced-tasks",
            label: "Advanced Tasks",
            autoGenerated: true,  // Auto-discover all files in guides/advanced-tasks/
        },
    ],
}

Files added to content/docs/guides/getting-started/ appear automatically under “Getting Started” subgroup.

Files added to content/docs/guides/advanced-tasks/ appear automatically under “Advanced Tasks” subgroup.

No config changes needed.

Mixed Auto and Manual

{
    id: "platform",
    label: "Platform",
    groups: [
        {
            id: "essentials",
            label: "Essentials",
            autoGenerated: true,  // Auto-discover
        },
        {
            id: "integration",
            label: "Integration",
            autoGenerated: false,  // Manual entries
            entries: [
                { slug: "platform/webhooks" },
                { slug: "platform/oauth" },
                { slug: "platform/rest-api" },
            ],
        },
    ],
}

essentials subgroup: Files appear automatically integration subgroup: Only listed entries appear

When to Use Single-Level Nesting

Perfect for:

  • Documentation with 2-3 organizational layers
  • Most projects and products
  • Clear category -> subcategory -> page structure
  • Team documentation
  • Feature documentation

Examples:

Getting Started
├── Installation
├── Configuration
└── First Steps

Features
├── Authentication
├── Database
└── API

Advanced
├── Performance
├── Security
└── Troubleshooting

Visual Navigation

Users see a navigation sidebar like:

Getting Started (Expanded)
  ├─ Installation
  ├─ Configuration
  └─ First Steps

Features (Expanded)
  ├─ Authentication
  ├─ Database
  └─ API

Advanced (Collapsed)
  └─ [+] Expand...

When they click “Advanced”, it expands to show Performance, Security, Troubleshooting.

When they’re viewing a page in “Performance”, sidebar shows:

Advanced (Expanded)
  ├─ Performance (Current section)
  ├─ Security
  └─ Troubleshooting

Performance

Single-level nesting is efficient:

  • Quick to navigate
  • Small navigation tree size
  • Fast rendering
  • Clear mental model

Compared to deeper nesting, users never get lost.

Comparison

Too shallow (no nesting):
├─ Getting Started
├─ Features
├─ Advanced
├─ API Reference
├─ Examples
├─ Troubleshooting
[Long list, hard to scan]

Single-level (perfect):
├─ Getting Started
│  ├─ Installation
│  ├─ Configuration
│  └─ First Steps
├─ Features
│  ├─ Authentication
│  ├─ Database
│  └─ API
└─ Advanced
   ├─ Performance
   ├─ Security
   └─ Troubleshooting
[Organized, scannable, not too deep]

Too deep (multiple levels):
├─ Docs
   ├─ Getting Started
   │  ├─ Installation
   │  │  ├─ Prerequisites
   │  │  ├─ Windows
   │  │  └─ macOS
   │  ├─ Configuration
   │  │  ├─ Basic
   │  │  ├─ Advanced
   │  │  └─ Custom
   └─ Features
[Hard to navigate, too much clicking]

Single-level is the sweet spot for most documentation.

Next Steps