---
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 CelestialDocs 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

CelestialDocs 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)