Understanding Nested Groups

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)

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

{
    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:

{
    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:

{
    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 - Promote groups to tabs
• Configuration Guide
• Real-World Examples