Search Documentation

Search for pages and headings in the documentation

Three-Tier Hierarchy Overview

Navigation Hierarchy Concept

PID^TOO|| uses a clean three-tier system to organize content. Understanding this structure is key to building effective documentation.

The Three Tiers

Tier 1: Entries (Pages)

The foundation�individual Markdown or MDX files representing one page.

Entry
��� One file = One page
��� E.g., guides/installation.md
��� Becomes URL: /docs/guides/installation
���� Shows in sidebar as a clickable link

Tier 2: Groups (Collections)

Collections of related entries organized into sidebar sections.

Group: "Getting Started"
��� Collapsible sidebar section
��� Contains multiple entries
��� Examples: Guides, Tutorials, Concepts
���� Can contain other groups (nested)

Tier 3: Tabs (Contexts)

Top-level navigation that switches the entire sidebar context.

Tab: "API Reference"
��� Appears at top of sidebar
��� Can be clicked to switch navigation context
��� Contains multiple groups
���� Perfect for separating major sections

Hierarchy Visualization

�����������������������������������������������������������������
�                     Web Browser                              �
�                                                              �
�  [Learn] [Getting Started] [API Reference] [Guides]         �
�  �� Tabs                                                       �
�                                                              �
�  ����������������������������������������������������������  �
�  � Sidebar (current tab: "Getting Started")             �  �
�  �                                                      �  �
�  �   Getting Started (Group)                         �  �
�  �    ��� Installation (Entry) <- clickable link       �  �
�  �    ��� Quick Start (Entry) <- clickable link        �  �
�  �    ���� Configuration (Entry) <- clickable link      �  �
�  �                                                      �  �
�  �  � Related Sections (Group)                        �  �
�  �    ��� FAQ (Entry)                                  �  �
�  �    ���� Troubleshooting (Entry)                      �  �
�  �                                                      �  �
�  ����������������������������������������������������������  �
�                                                              �
�  (When user clicks "API Reference" tab, entire sidebar     �
�   switches to show that tab's groups and entries)          �
�����������������������������������������������������������������

How They Connect

File System -> Configuration -> UI

Step 1: File System
    content/my-docs/
    ��� getting-started/
    �   ��� introduction.md        (File)
    �   ��� installation.md        (File)
    �   ���� quick-start.md         (File)
    ���� api/
        ��� endpoints.md           (File)
        ���� authentication.md      (File)

            � (Configuration connects files to groups)

Step 2: Configuration (data/config.ts)
    groups: [
        {
            id: "getting-started",
            label: "Getting Started",
            autoGenerated: true,  <- Discovers files from folder
        },
        {
            id: "api",
            label: "API Reference",
            tab: true,            <- Makes this a tab
            autoGenerated: true,
        },
    ]

            � (System renders configuration as UI)

Step 3: User Interface
    [Learn] [Getting Started] [API Reference]  <- Tabs

     Getting Started                    <- Group
    ��� Introduction                      <- Entry
    ��� Installation                      <- Entry
    ���� Quick Start                       <- Entry

Full Example: Placing an Entry

Let’s trace how a single file becomes a clickable link:

1. Create the File

# content/my-docs/guides/performance.md

---

title: "Performance Optimization"
description: "Tips for optimizing your system"

---

# Performance Optimization

Content about performance...

2. Register the Collection

// data/config.ts
export const CONTENT = {
    systems: [
        {
            id: "my-docs",
            dir: "content/my-docs",
            route: "/my-docs",
        },
    ],
};

3. Configure the Group

// data/config.ts
export const SIDEBAR_NAVIGATION = {
    "my-docs": {
        defaultTab: { label: "Docs", icon: "�" },
        groups: [
            {
                id: "guides",
                label: "User Guides",
                autoGenerated: true, // Scans content/my-docs/guides/
            },
        ],
    },
};

4. Result

  • File: content/my-docs/guides/performance.md
  • Slug: guides/performance
  • URL: https://yourdocs.com/my-docs/guides/performance
  • Sidebar: Shows “Performance Optimization” under “User Guides” group
  • Navigation: Clickable link that users can click to read the page

Scaling the Hierarchy

The three-tier system scales beautifully:

Small Documentation (10-50 pages)

���� Default Tab
    ���� Single Group (auto-generated)
        ��� Entry 1
        ��� Entry 2
        ���� Entry 3

Medium Documentation (50-200 pages)

���� Default Tab
    ��� Group 1 (Getting Started)
    ��� Group 2 (Features)
    ���� Group 3 (Advanced)

Large Documentation (200-1000 pages)

��� Tab 1: User Guide
�   ��� Group 1: Getting Started
�   ��� Group 2: Features
�   �   ��� Subgroup A
�   �   ���� Subgroup B
�   ���� Group 3: Advanced
��� Tab 2: API Reference
�   ��� Group 1: Endpoints
�   ��� Group 2: Authentication
�   ���� Group 3: Webhooks
���� Tab 3: Patterns & Examples
    ���� Group 1: Common Patterns (auto-generated)

Enterprise Documentation (1000+ pages)

��� Tab 1: Getting Started
��� Tab 2: User Documentation
�   ��� Group: Basics
�   ��� Group: Intermediate
�   �   ��� Subgroup: Configuration
�   �   ���� Subgroup: Deployment
�   ���� Group: Advanced
�       ��� Subgroup: Performance
�       ��� Subgroup: Security
�       ���� Subgroup: Architecture
��� Tab 3: API Reference
�   ��� Group: v1 (Legacy)
�   ���� Group: v2 (Current)
�       ��� Subgroup: Authentication
�       ��� Subgroup: Endpoints
�       ���� Subgroup: Webhooks
���� Tab 4: Help & Support

Key Principles

  1. Entries are leaves - They’re always at the bottom; you can’t put groups inside entries
  2. Groups are organizational - They exist to group entries logically
  3. Tabs are contextual - They switch entire navigation experiences
  4. Nesting has limits - 3-4 levels is usually optimal; more gets confusing
  5. Structure mirrors files - Your folder structure should match your navigation

Next Steps

Now understand the visual representation:

Or learn to configure: