Navigation Configuration

The navigation section controls how users move through your documentation. Configure the sidebar, breadcrumbs, table of contents, and tab groups to create an intuitive navigation experience.

Basic Configuration

Here's a minimal navigation setup:

1{
2  "navigation": {
3    "showSidebar": true,
4    "showBreadcrumbs": true,
5    "showTableOfContents": true
6  }
7}

Specra provides sensible defaults, so you only need to configure what you want to change.

Complete Configuration

1{
2  "navigation": {
3    "showSidebar": true,
4    "collapsibleSidebar": true,
5    "showBreadcrumbs": true,
6    "showTableOfContents": true,
7    "tocPosition": "right",
8    "tocMaxDepth": 3,
9    "tabGroups": [
10      {
11        "id": "guides",
12        "label": "Guides",
13        "icon": "book-open"
14      },
15      {
16        "id": "api",
17        "label": "API Reference",
18        "icon": "zap"
19      },
20      {
21        "id": "components",
22        "label": "Components",
23        "icon": "layers"
24      }
25    ]
26  }
27}

Sidebar Configuration

showSidebar

Type: boolean Default: true

Show or hide the sidebar navigation.

1{
2  "navigation": {
3    "showSidebar": true
4  }
5}

Set to false to hide the sidebar completely. Useful for landing pages or marketing sites.

collapsibleSidebar

Type: boolean Default: true

Allow users to collapse and expand sidebar sections.

1{
2  "navigation": {
3    "collapsibleSidebar": true
4  }
5}

When true, folder sections have collapse/expand arrows. When false, all sections are always expanded.

Breadcrumbs

showBreadcrumbs

Type: boolean Default: true

Display breadcrumb navigation at the top of each page.

1{
2  "navigation": {
3    "showBreadcrumbs": true
4  }
5}

Breadcrumbs show the page's location in the documentation hierarchy:

Home > Guides > Getting Started

Table of Contents

showTableOfContents

Type: boolean Default: true

Display the table of contents (TOC) on documentation pages.

1{
2  "navigation": {
3    "showTableOfContents": true
4  }
5}

The TOC shows all headings on the current page with links to scroll to each section.

tocPosition

Type: "left" or "right" Default: "right"

Position the table of contents on the left or right side of the page.

1{
2  "navigation": {
3    "tocPosition": "right"
4  }
5}

Right position (default):

• TOC appears in the right sidebar
• Traditional documentation layout
• More reading space for content

Left position:

• TOC appears in the left sidebar below main navigation
• Compact layout
• Less horizontal scrolling on smaller screens

tocMaxDepth

Type: number (1-6) Default: 3

Maximum heading level to show in the table of contents.

1{
2  "navigation": {
3    "tocMaxDepth": 3
4  }
5}

Options:

• 1 - Only H1 headings
• 2 - H1 and H2 headings
• 3 - H1, H2, and H3 headings (recommended)
• 4 - Up to H4
• 5 - Up to H5
• 6 - All headings

Tab Groups

Tab groups organize your documentation into logical sections with separate navigation tabs.

Basic Tab Groups

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

Tab Group Properties

Each tab group has three properties:

id (required)

• Unique identifier for the tab group
• Used in page frontmatter: tab_group: "guides"
• Lowercase, no spaces

label (required)

• Display name shown in the tab
• Can include spaces and capitalization

icon (optional)

• Lucide icon name to display next to label
• Makes tabs more visual and scannable

Assigning Pages to Tab Groups

In your MDX frontmatter, specify which tab group a page belongs to:

1---
2title: Getting Started
3tab_group: guides
4---

Pages with the same tab_group value appear together under that tab.

Common Tab Group Setups

Documentation + API:

1{
2  "tabGroups": [
3    {
4      "id": "docs",
5      "label": "Documentation",
6      "icon": "book"
7    },
8    {
9      "id": "api",
10      "label": "API Reference",
11      "icon": "code"
12    }
13  ]
14}

Guides + Components + API:

1{
2  "tabGroups": [
3    {
4      "id": "guides",
5      "label": "Guides",
6      "icon": "book-open"
7    },
8    {
9      "id": "components",
10      "label": "Components",
11      "icon": "layers"
12    },
13    {
14      "id": "api",
15      "label": "API",
16      "icon": "zap"
17    }
18  ]
19}

Multi-product documentation:

1{
2  "tabGroups": [
3    {
4      "id": "platform",
5      "label": "Platform",
6      "icon": "box"
7    },
8    {
9      "id": "mobile",
10      "label": "Mobile SDK",
11      "icon": "smartphone"
12    },
13    {
14      "id": "web",
15      "label": "Web SDK",
16      "icon": "monitor"
17    }
18  ]
19}

Available Icons

Specra uses Lucide icons. Popular choices for documentation:

General:

• book - Books, documentation
• book-open - Open book, reading
• file-text - Documents, pages
• layout - Layout, structure

Technical:

• code - Code, programming
• zap - API, fast, dynamic
• terminal - CLI, command line
• database - Database, data

UI:

• layers - Components, stack
• palette - Design, theming
• settings - Configuration
• grid - Layout grid

Actions:

• rocket - Launch, deployment
• wrench - Tools, utilities
• shield - Security
• search - Search, find

Browse all icons at lucide.dev

Sidebar Organization

Automatic Generation

Specra automatically generates your sidebar from your file structure:

1docs/v1.0.0/
2├── getting-started.mdx        → Getting Started
3├── installation.mdx           → Installation
4└── guides/                    → Guides (folder)
5    ├── basics.mdx            →   Basics
6    └── advanced.mdx          →   Advanced

Controlling Order

Use sidebar_position in frontmatter to control page order:

1---
2title: Getting Started
3sidebar_position: 1
4---

Lower numbers appear first. Pages without positions are sorted alphabetically.

Category Configuration

Customize folder appearance with _category_.json:

1{
2  "label": "User Guides",
3  "position": 2,
4  "collapsible": true,
5  "collapsed": false,
6  "icon": "book-open"
7}

See Writing Content for more on organizing content.

Examples

Minimal Setup

Just enable the basics:

1{
2  "navigation": {
3    "showSidebar": true,
4    "showBreadcrumbs": true,
5    "showTableOfContents": true
6  }
7}

Clean Layout

TOC on left, deeper headings:

1{
2  "navigation": {
3    "showSidebar": true,
4    "collapsibleSidebar": true,
5    "showBreadcrumbs": true,
6    "showTableOfContents": true,
7    "tocPosition": "left",
8    "tocMaxDepth": 4
9  }
10}

Multi-Section Documentation

With tab groups for different audiences:

1{
2  "navigation": {
3    "showSidebar": true,
4    "collapsibleSidebar": true,
5    "showBreadcrumbs": true,
6    "showTableOfContents": true,
7    "tocPosition": "right",
8    "tocMaxDepth": 3,
9    "tabGroups": [
10      {
11        "id": "getting-started",
12        "label": "Getting Started",
13        "icon": "rocket"
14      },
15      {
16        "id": "developers",
17        "label": "Developers",
18        "icon": "code"
19      },
20      {
21        "id": "designers",
22        "label": "Designers",
23        "icon": "palette"
24      }
25    ]
26  }
27}

Best Practices

Use tab groups wisely - Don't create too many. 3-5 tabs maximum works best.

Choose descriptive labels - Make it obvious what's in each tab or section.

Pick appropriate icons - Icons should reinforce the tab's purpose.

Set tocMaxDepth appropriately - Most docs work best with 2 or 3 levels.

Keep sidebar collapsible - Let users hide sections they don't need.

Show breadcrumbs - They help users navigate complex documentation.

Next Steps