Tab Groups

Tab groups allow you to organize your documentation into different sections accessible through tabs at the top of your documentation pages. This is particularly useful for separating different types of content like SDK docs, API references, and guides.

Overview

Tab groups provide a sticky navigation bar that:

• Sits below the header
• Filters sidebar content based on the active tab
• Persists across page navigation
• Supports icons from Lucide React
• Maintains auto-generated sidebar structure

Configuration

Define tab groups in your specra.config.json:

1{
2  "navigation": {
3    "tabGroups": [
4      {
5        "id": "sdk",
6        "label": "SDK Documentation",
7        "icon": "code"
8      },
9      {
10        "id": "api",
11        "label": "API Reference",
12        "icon": "zap"
13      },
14      {
15        "id": "guides",
16        "label": "Guides",
17        "icon": "book-open"
18      }
19    ]
20  }
21}

Tab Group Properties

Assigning Content to Tabs

There are two ways to assign content to tab groups:

1. File-Level Assignment

Add tab_group to the frontmatter of your MDX files:

1---
2title: Getting Started
3description: Quick start guide
4tab_group: guides
5---
6 
7# Getting Started
8 
9Your content here...

2. Folder-Level Assignment

Add tab_group to your _category_.json file to assign all files in that folder:

1{
2  "label": "Components",
3  "position": 2,
4  "collapsible": true,
5  "collapsed": false,
6  "icon": "grid",
7  "tab_group": "sdk"
8}

All files within this folder will automatically inherit the sdk tab group.

Behavior and Rules

Default Tab Assignment

Files without a tab_group specified will automatically appear in the first tab group defined in your config.

Precedence

File-level tab_group in frontmatter takes precedence over folder-level assignment from _category_.json.

Tab Persistence

The active tab persists when:

• Navigating between pages within the same tab group
• Manually switching tabs
• Clicking links to pages in different tab groups (tab switches automatically)

Initial Tab Selection

When you land on a page:

• The tab automatically switches to match the page's tab group
• On page reload, the tab reflects the current page's group
• Manual tab selection is preserved when navigating within the same group

Best Practices

1. Logical Grouping

Group related content together:

• SDK/Library docs: Installation, configuration, API reference
• API docs: REST endpoints, GraphQL schemas, webhooks
• Guides: Tutorials, how-tos, best practices

2. Consistent Naming

Use clear, concise labels:

• ✅ "SDK Documentation", "API Reference", "Guides"
• ❌ "Docs1", "Section A", "Misc"

3. Meaningful Icons

Choose icons that represent the content:

• code for SDK/library documentation
• zap for API references
• book-open for guides and tutorials
• rocket for getting started content

4. Limit Tab Count

Keep the number of tabs manageable:

• Recommended: 2-4 tabs
• Maximum: 5-6 tabs
• Too many tabs can overwhelm users

Examples

Example 1: Simple SDK + API Split

1{
2  "navigation": {
3    "tabGroups": [
4      {
5        "id": "sdk",
6        "label": "SDK",
7        "icon": "code"
8      },
9      {
10        "id": "api",
11        "label": "API",
12        "icon": "zap"
13      }
14    ]
15  }
16}

Example 2: Comprehensive Documentation

1{
2  "navigation": {
3    "tabGroups": [
4      {
5        "id": "getting-started",
6        "label": "Getting Started",
7        "icon": "rocket"
8      },
9      {
10        "id": "sdk",
11        "label": "SDK Reference",
12        "icon": "code"
13      },
14      {
15        "id": "api",
16        "label": "API Reference",
17        "icon": "server"
18      },
19      {
20        "id": "guides",
21        "label": "Guides",
22        "icon": "book-open"
23      }
24    ]
25  }
26}

Advanced Usage

Nested Folders

Tab groups work seamlessly with nested folder structures:

1docs/v1.0.0/
2├── components/              # tab_group: sdk
3│   ├── _category_.json
4│   ├── button.mdx
5│   └── input.mdx
6├── api/                     # tab_group: api
7│   ├── _category_.json
8│   ├── authentication.mdx
9│   └── endpoints.mdx
10└── guides/                  # tab_group: guides
11    ├── _category_.json
12    └── quickstart.mdx       # Can override with file-level tab_group

Mixed Tab Groups in Same Folder

You can have files in the same folder belong to different tabs:

1docs/v1.0.0/
2├── _category_.json          # Default: tab_group: sdk
3├── overview.mdx             # Inherits: sdk
4├── api-overview.mdx         # Override: tab_group: api
5└── tutorial.mdx             # Override: tab_group: guides

Troubleshooting

Tab Not Showing

Problem: Tab group defined but not visible

Solutions:

• Ensure at least one file is assigned to that tab group
• Check that the tab group id matches exactly in both config and frontmatter
• Verify navigation.tabGroups is defined in specra.config.json

Content Appearing in Wrong Tab

Problem: Page shows up under incorrect tab

Solutions:

• Check file-level frontmatter for tab_group override
• Verify folder-level _category_.json has correct tab_group
• Remember: frontmatter takes precedence over _category_.json

Tab Not Persisting

Problem: Tab resets when navigating

Solutions:

• This is expected behavior when navigating to a page in a different tab group
• The tab automatically switches to match the current page's group
• Manual selection persists only when navigating within the same tab group

Comparison with Alternatives

vs. Mintlify/Docusaurus

Unlike Mintlify and Docusaurus which require manual sidebar configuration, our tab groups:

• ✅ Auto-generate sidebar structure from folder hierarchy
• ✅ Support both file and folder-level assignments
• ✅ Persist tab state across navigation
• ✅ Automatically filter sidebar content
• ✅ Require minimal configuration

Advantages

1. Auto-generation: No need to manually maintain sidebar structure
2. Flexibility: File-level overrides for granular control
3. Persistence: Smart tab state management
4. Icons: Built-in icon support from Lucide React
5. Sticky Navigation: Tabs stay visible while scrolling

Related

• Sidebar Configuration
• Navigation Settings
• Folder Structure