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