Hierarchical Navigation Power

PID^TOO||’ three-tier hierarchy (Entries -> Groups -> Tabs) is specifically designed to scale documentation from tiny to enterprise-scale without requiring deep nesting or complexity.

The Hierarchy Advantage

Tier 1: Entries (Pages)

Individual files, clickable links

Tier 2: Groups (Collections)

Organize related entries into sidebar sections

Tier 3: Tabs (Contexts)

Switch between major documentation sections

Why three tiers?

One tier (flat): Okay for 10 pages, chaos for 100
Two tiers: Good for 50-200 pages, gets convoluted
Three tiers: Perfect for 100-10,000 pages
Four+ tiers: Causes navigation fatigue

Real-World Scaling

Small Project (10-50 pages)

[Learn]
��� Getting Started
�   ��� Intro
�   ���� Install
��� Features
���� Help

Configuration: 3-4 groups, auto-generated Complexity: Trivial

Medium Project (50-200 pages)

[Learn] [API] [Patterns]
��� Getting Started
��� Guides
�   ��� Authentication
�   ��� Deployment
�   ���� Testing
��� Advanced
    ���� (auto-gen)

Configuration: Multiple groups, some nesting Complexity: Moderate

Large Project (200-1000 pages)

[Getting Started] [User Docs] [API Reference] [Patterns]
��� Learn
��� Configuration
�   ��� Basics
�   ��� Advanced
�   �   ��� Caching
�   �   ��� Performance
�   �   ���� Security
�   ���� Deployment
���� Reference

Configuration: Deep nesting, multiple tabs Complexity: Managed

Enterprise (1000+ pages)

[Docs] [API v1] [API v2] [API v3] [SDKs] [Community] [Help]
��� User Guide
��� Admin Guide
�   ��� Configuration
�   �   ��� Basics
�   �   ��� Advanced
�   �   ���� Automation
�   ��� Deployment
�   ��� Security
�   ���� Monitoring
��� Integration Guide
���� Reference

Configuration: Complex nesting, many tabs Complexity: High but manageable

Why This Scales

1. Logical Organization

Content organized by meaning, not arbitrary depth

2. Flexible Nesting

Can nest 2-3 levels for organization without UI clutter

3. Tab Separation

Tabs act as “reset buttons” - switch contexts completely

4. Auto-Generation at Any Level

Auto-discovery works at every nesting level

5. Type Safety

All configuration is TypeScript - errors caught early

Comparison: Other Systems

MkDocs (File-based)

docs/
��� index.md
��� guide/
�   ��� index.md
�   ��� installation.md
�   ���� quickstart.md
��� api/
�   ��� index.md
�   ���� reference.md

Problem: Navigation structure locked to file system Solution: Manual YAML config that duplicates structure

sidebar:
    - label: "Getting Started"
      items:
          - id: "getting-started/index"
          - label: "Installation"
            id: "getting-started/installation"

Problem: Manual config grows unwieldy (1000+ lines) Solution: None - config scales with documentation

PID^TOO|| (Smart hierarchy)

{
    id: "getting-started",
    label: "Getting Started",
    autoGenerated: true,
}

Benefit: Config is compact, auto-discovers as docs grow Scales: Configuration stays manageable at 1000+ pages

Concrete Benefits

For Documentation Maintainers

Clarity

Clear structure: Docs -> Guides -> Advanced Topics -> Troubleshooting
vs.
"Where does this page go?"

Maintainability

One group grows? Fine, it auto-discovers
New tab needed? Add one tab, not restructure everything

Flexibility

Can promote subgroup to tab without refactoring
Can nest groups for organization without clutter

For Documentation Readers

Intuitive Navigation

Users understand the structure at a glance
Tabs separate concerns (guides vs. API)
Groups organize related content

Never Lost

Breadcrumbs show: Home > Guides > Advanced > Performance
Users always know where they are

Discoverable

All content findable through navigation
No "hidden" corners of documentation

For Teams

Grow Without Refactoring

Month 1: 5 groups
Month 6: 5 groups (more entries in each)
Month 12: Add 2 tabs, still same structure

Coordinate Easier

Teams work on different tabs independently
No merge conflicts from reordering

Onboard Faster

New team member: "Just add markdown files"
No need to understand complex hierarchy

Example: This Documentation

This site demonstrates the power:

[Overview]
[Getting Started] - Sequential learning
[Navigation System] - Core concepts with 2-level nesting
[Configuration] - Advanced 3-level hierarchy
[Generation Strategies] - Three different approaches
[Content] - Markdown + frontmatter
[Advanced Topics] - Multiple selling points

Structure:

7 top-level tabs
Some with nested groups
Some auto-generated sections
Mix of manual and automatic

Scales: Add a new tab, everything works Maintains: Config file still manageable Grows: New pages auto-discovered automatically

Selling Points

Starts Simple, Scales Complex “Works perfectly whether you have 10 pages or 10,000”
No Reorg as You Grow “Add tabs and groups, never restructure existing navigation”
Flexible Nesting “2-3 levels for organization, unlimited scalability”
User-Friendly “Breadcrumbs and clear hierarchy mean users never get lost”
Type-Safe “Configuration errors caught at development time”

Next: Learn other selling points:

Search Documentation