Understanding Nested Groups

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)

{
    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