Three-Tier Hierarchy Overview
CelestialDocs 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 linkTier 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 sectionsHierarchy 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 <- EntryFull 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 3Medium 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 & SupportKey Principles
- Entries are leaves - They’re always at the bottom; you can’t put groups inside entries
- Groups are organizational - They exist to group entries logically
- Tabs are contextual - They switch entire navigation experiences
- Nesting has limits - 3-4 levels is usually optimal; more gets confusing
- Structure mirrors files - Your folder structure should match your navigation
Next Steps
Now understand the visual representation:
Or learn to configure: