---
title: "Understanding Nested Groups"
description: "Learn how to create hierarchies within groups for complex documentation structures"
---

**Nested Groups** are groups within groups, creating a deeper hierarchy. This is where PID^TOO|| truly shines for complex documentation.

## What are Nested Groups?

A nested group is a group that contains subgroups instead of (or in addition to) entries:

```
Group: "Advanced Topics"
��� Subgroup: "Performance"
�   ��� Entry: Caching Strategies
�   ��� Entry: Database Optimization
�   ���� Entry: Load Balancing
��� Subgroup: "Security"
�   ��� Entry: Authentication
�   ��� Entry: Authorization
�   ���� Entry: Encryption
���� Subgroup: "Deployment"
    ��� Entry: Docker Setup
    ��� Entry: Kubernetes Config
    ���� Entry: CI/CD Pipeline
```

## Hierarchy Levels

PID^TOO|| supports unlimited nesting depth:

```
Level 1: Tab (or Default Tab)
���� Level 2: Group
    ���� Level 3: Subgroup
        ���� Level 4: Sub-subgroup
            ���� Level 5: Entries
```

In practice, keep it to 3-4 levels for UX reasons�beyond that, navigation becomes complex.

## Creating Nested Groups

Nested groups are defined using the `groups` property instead of `entries`:

### Simple Nesting (2 Levels)

```typescript
{
    id: "configuration",
    label: "Configuration",
    icon: "",
    groups: [
        {
            id: "basics",
            label: "Basics",
            entries: [
                { slug: "configuration/basics/overview" },
                { slug: "configuration/basics/setup" },
            ],
        },
        {
            id: "advanced",
            label: "Advanced",
            entries: [
                { slug: "configuration/advanced/caching" },
                { slug: "configuration/advanced/security" },
            ],
        },
    ],
}
```

**Sidebar renders as:**

```
 Configuration
��� Basics
�   ��� Overview
�   ���� Setup
���� Advanced
    ��� Caching
    ���� Security
```

### Deeper Nesting (3+ Levels)

```typescript
{
    id: "advanced",
    label: "Advanced Topics",
    icon: "",
    groups: [
        {
            id: "architecture",
            label: "Architecture",
            groups: [
                {
                    id: "patterns",
                    label: "Design Patterns",
                    entries: [
                        { slug: "advanced/architecture/patterns/observer" },
                        { slug: "advanced/architecture/patterns/factory" },
                    ],
                },
                {
                    id: "performance",
                    label: "Performance",
                    entries: [
                        { slug: "advanced/architecture/performance/caching" },
                        { slug: "advanced/architecture/performance/optimization" },
                    ],
                },
            ],
        },
    ],
}
```

**Sidebar renders as:**

```
 Advanced Topics
���� Architecture
    ��� Design Patterns
    �   ��� Observer
    �   ���� Factory
    ���� Performance
        ��� Caching
        ���� Optimization
```

## Mixing Entries and Subgroups

A group can have both entries and subgroups:

```typescript
{
    id: "features",
    label: "Features",
    entries: [
        { slug: "features/overview" },  // Top-level entries
    ],
    groups: [
        {
            id: "authentication",
            label: "Authentication",
            entries: [
                { slug: "features/auth/oauth" },
                { slug: "features/auth/saml" },
            ],
        },
    ],
}
```

**Sidebar renders as:**

```
Features
��� Overview              (entry at group level)
���� Authentication        (subgroup)
    ��� OAuth
    ���� SAML
```

## File Structure for Nested Groups

Your content folder structure should reflect your nested organization:

```
content/my-docs/
��� advanced/
�   ��� architecture/
�   �   ��� patterns/
�   �   �   ��� observer.md
�   �   �   ���� factory.md
�   �   ���� performance/
�   �       ��� caching.md
�   �       ���� optimization.md
�   ��� security/
�   �   ��� authentication.md
�   �   ���� encryption.md
```

This matches the configuration structure, making it intuitive.

## Auto-Generation with Nested Groups

Auto-generation works at every nesting level:

```typescript
{
    id: "documentation",
    label: "Documentation",
    groups: [
        {
            id: "guides",
            label: "Guides",
            autoGenerated: true,  // Scans content/my-docs/documentation/guides/
        },
        {
            id: "api-reference",
            label: "API Reference",
            groups: [
                {
                    id: "endpoints",
                    label: "Endpoints",
                    autoGenerated: true,  // Scans content/my-docs/documentation/api-reference/endpoints/
                },
            ],
        },
    ],
}
```

## Real-World Example

This site's own structure demonstrates nested groups. Open the sidebar and see:

```
Navigation System (Tab)
��� Core Concepts (Group)
�   ��� Entries
�   ��� Groups
�   ��� Nested Groups       <- You're reading this!
�   ���� Tabs
��� Hierarchy (Group)
�   ��� Three-Tier Overview
�   ��� Visual Guide
�   ���� Real-World Examples
```

## Benefits of Nested Groups

 **Scalability**: Organize 10 pages or 10,000 pages
 **Clarity**: Deep hierarchies are intuitive for complex topics
 **Flexibility**: Mix manual and auto-generated at each level
 **User Experience**: Users understand the structure immediately

## When to Use Nested Groups

-  Large documentation (100+ pages)
-  Multiple related topics (e.g., different API versions)
-  Tutorials with many chapters
-  Enterprise systems with complex features

## When NOT to Use Nested Groups

- � Very small documentation (under 20 pages�keep it flat)
- � Unrelated topics (use tabs instead for organization)
- � More than 4-5 nesting levels (affects UX)

## Next Steps

Learn about:

- [Tabs](/docs/navigation-system/core-concepts/tabs) - Promote groups to tabs
- [Configuration Guide](/docs/configuration/advanced/nested-setup/single-level)
- [Real-World Examples](/docs/navigation-system/hierarchy/real-world-examples)