Creating Tabs

Tabs are top-level navigation elements that split your documentation into separate sections. Think of tabs as completely independent view modes.

What Are Tabs?

┌──────────────────────────────────┐
│ Getting Started │  API  │ Guides │  <- Tabs
├──────────────────────────────────┤
│ Sidebar Content for selected tab │
│                                  │
│ Current tab: Getting Started     │
└──────────────────────────────────┘

Clicking a tab switches the entire sidebar navigation.

Creating Your First Tab

Step 1: Define in Configuration

export const SIDEBAR_NAVIGATION = {
    docs: {
        defaultTab: {
            label: "Getting Started",
            icon: "🚀",
        },
        groups: [
            {
                id: "quickstart",
                label: "Quick Start",
                tab: true, // <- This makes it a tab!
                autoGenerated: true,
            },
            {
                id: "guides",
                label: "How-To Guides",
                tab: true, // <- Another tab
                autoGenerated: true,
            },
            {
                id: "reference",
                label: "Reference",
                tab: true, // <- Third tab
                autoGenerated: true,
            },
        ],
    },
};

Key: Set tab: true to promote a group to a tab.

Step 2: Create Folder Structure

content/docs/
├─ quickstart/           <- Matches "quickstart" tab
│  ├─ intro.md
│  ├─ setup.md
│  └─ first-app.md
├─ guides/               <- Matches "guides" tab
│  ├─ authentication.md
│  ├─ database.md
│  └─ deployment.md
└─ reference/            <- Matches "reference" tab
   ├─ api.md
   ├─ cli.md
   └─ config.md

Step 3: User Experience

Users see tabs:

┌─────────────────────────────────┐
│ Quickstart │ Guides │ Reference │
└─────────────────────────────────┘

Content below changes based on selected tab.

On Quickstart tab:
├─ Introduction
├─ Setup
└─ First App

On Guides tab:
├─ Authentication
├─ Database
└─ Deployment

On Reference tab:
├─ API
├─ CLI
└─ Config

Clicking tabs switches navigation entirely.

Tab with Nested Groups

Tabs can contain groups (creating another level of navigation):

{
    id: "api",
    label: "API",
    tab: true,
    groups: [
        {
            id: "authentication",
            label: "Authentication",
            autoGenerated: true,
        },
        {
            id: "resources",
            label: "Resources",
            groups: [
                { id: "users", label: "Users", autoGenerated: true },
                { id: "posts", label: "Posts", autoGenerated: true },
                { id: "comments", label: "Comments", autoGenerated: true },
            ],
        },
        {
            id: "errors",
            label: "Error Handling",
            autoGenerated: true,
        },
    ],
}

Navigation:

Tabs: [Quickstart] [API] [Reference]

When on API tab, sidebar shows:
├─ Authentication
├─ Resources
│  ├─ Users
│  ├─ Posts
│  └─ Comments
└─ Error Handling

Tabs + nested groups = powerful organization.

Tab Icons

Icons help users identify tabs quickly:

defaultTab: {
    label: "Getting Started",
    icon: "🚀",  // <- Rocket for quick start
},
groups: [
    {
        id: "getting-started",
        label: "Getting Started",
        tab: true,
        icon: "📖",  // <- Book icon
    },
    {
        id: "api",
        label: "API Reference",
        tab: true,
        icon: "🔗",  // <- Link icon
    },
    {
        id: "examples",
        label: "Examples",
        tab: true,
        icon: "💡",  // <- Lightbulb icon
    },
],

Icons appear with tab labels. Users recognize patterns:

🚀 Getting Started
🔗 API
💡 Examples
⚙️ Configuration
🛠️ Advanced

Tab Selection State

Tabs remember selection. If user navigates to:

/docs/api/endpoints

And selects “Reference” tab, sidebar updates but URL pattern changes:

/docs/reference/overview

Breadcrumb updates:

Before: Home > Docs > API > Endpoints
After:  Home > Docs > Reference > Overview

Each tab maintains its own content and breadcrumb trail.

Common Tab Structures

Structure 1: By User Journey

Getting Started -> Learn -> Build -> Deploy -> Reference

groups: [
    { id: "getting-started", label: "Getting Started", tab: true, ... },
    { id: "learn", label: "Learn", tab: true, ... },
    { id: "build", label: "Build", tab: true, ... },
    { id: "deploy", label: "Deploy", tab: true, ... },
    { id: "reference", label: "Reference", tab: true, ... },
]

New users start with “Getting Started” tab. Advanced users jump to “Reference” tab.

Structure 2: By Audience

Users | Developers | Operators

groups: [
    { id: "users", label: "Users", tab: true, ... },
    { id: "developers", label: "Developers", tab: true, ... },
    { id: "operators", label: "Operators", tab: true, ... },
]

Each audience sees relevant content in their tab.

Structure 3: By Product

Core | Extensions | Plugins | Marketplace

groups: [
    { id: "core", label: "Core", tab: true, ... },
    { id: "extensions", label: "Extensions", tab: true, ... },
    { id: "plugins", label: "Plugins", tab: true, ... },
    { id: "marketplace", label: "Marketplace", tab: true, ... },
]

Each product/feature gets its own tab.

Structure 4: By Version

v3 (Current) | v2 (LTS) | v1 (Legacy)

groups: [
    { id: "v3-current", label: "v3 (Current)", tab: true, ... },
    { id: "v2-lts", label: "v2 (LTS)", tab: true, ... },
    { id: "v1-legacy", label: "v1 (Legacy)", tab: true, ... },
]

Users select their version, see relevant docs.

Switching Between Tabs

Manual Tab Click

User clicks “API” tab -> sidebar changes -> breadcrumb updates -> URL changes.

Was viewing: /docs/guides/authentication
Clicked: API tab
Now viewing: /docs/api/overview (or defaultTab for API)

Default Tab

If user visits /docs/ (no specific page), they see:

defaultTab: { label: "Getting Started", icon: "🚀" }

They land on Getting Started tab’s first page.

Deep Linking

Users can share direct links to specific tabs:

/docs/api/endpoints -> Opens API tab, shows endpoints
/docs/guides/setup -> Opens Guides tab, shows setup
/docs/reference/config -> Opens Reference tab, shows config

Clicking those links automatically switches to correct tab.

Tab + Manual Control

Mix tabs with manual entries:

groups: [
    {
        id: "essentials",
        label: "Essentials",
        tab: true,
        autoGenerated: false,
        entries: [
            { slug: "essentials/why-choose-us" },
            { slug: "essentials/features" },
            { slug: "essentials/pricing" },
        ],
    },
    {
        id: "guides",
        label: "Guides",
        tab: true,
        autoGenerated: true, // Auto-discover all files
    },
    {
        id: "api",
        label: "API",
        tab: true,
        autoGenerated: false,
        entries: [{ slug: "api/authentication" }, { slug: "api/endpoints" }],
    },
];

Result:

Essentials tab: 3 specific pages only
Guides tab: all files appear automatically
API tab: only listed endpoints appear

Performance Notes

Each tab loads sidebar content separately:

First load: Tab 1 loads
Click Tab 2: Tab 2’s sidebar loads (lazy)
Click Tab 3: Tab 3’s sidebar loads (lazy)

No performance impact from multiple tabs.

Responsive Behavior

On mobile, tabs stack or become dropdowns:

Desktop (3+ tabs):
[Getting Started] [API] [Reference] [Advanced]

Tablet (2-3 tabs):
[Getting Started] [API] [Reference] [▼ More]

Mobile (1+ tab):
Getting Started ▼  (dropdown)

Users can still access all tabs on mobile via dropdown.

Migration: Groups to Tabs

Converting existing groups to tabs:

Before (No tabs)

groups: [
    { id: "intro", label: "Introduction", autoGenerated: true },
    { id: "guides", label: "Guides", autoGenerated: true },
    { id: "reference", label: "Reference", autoGenerated: true },
];

Sidebar shows 3 groups, all in same view.

After (With tabs)

groups: [
    { id: "intro", label: "Introduction", tab: true, autoGenerated: true },
    { id: "guides", label: "Guides", tab: true, autoGenerated: true },
    { id: "reference", label: "Reference", tab: true, autoGenerated: true },
];

Same content, now organized with tabs. Just add tab: true.

Search Documentation