Automatic Navigation Generation

One of Rspress's most powerful features is its ability to automatically generate navigation bars and sidebars from your file structure and frontmatter metadata. This reduces manual configuration and keeps your navigation in sync with your content.

Understanding Auto-generation

How It Works

Rspress scans your documentation directory and:

Reads file structure (directories and files)
Parses frontmatter metadata from each file
Generates navigation based on conventions and configuration
Updates navigation dynamically as content changes

Benefits

Reduced Configuration: Less manual config to maintain
Always in Sync: Navigation updates with content changes
Consistent Structure: Enforces organizational patterns
Faster Development: Focus on content, not configuration

Frontmatter Metadata

Basic Frontmatter

Add metadata to the top of any Markdown file:

markdown

---
title: Getting Started Guide
description: Learn how to get started with Rspress
---

# Getting Started Guide

Your content here...

Control how pages appear in navigation:

markdown

---
title: Advanced Configuration
sidebar_position: 3
sidebar_label: Config Advanced
---

# Advanced Configuration

Content...

Complete Frontmatter Reference

markdown

---
# Page metadata
title: Page Title                    # Used in navigation and page title
description: Page description        # Used for SEO

# Navigation control
sidebar_position: 2                  # Order in sidebar (lower = first)
sidebar_label: Custom Label          # Override title in sidebar
nav_exclude: false                   # Hide from navigation

# Grouping
group: Getting Started              # Group this page belongs to
group_order: 1                      # Order within group

# Advanced
slug: /custom-url                   # Custom URL path
---

Enable Auto-generation

Enable automatic sidebar generation:

typescript

// rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': 'auto',  // Auto-generate for /guide/ section
    },
  },
});

File-based Structure

With auto-generation enabled, your file structure becomes your sidebar:

docs/guide/
├── index.md              # Getting Started (sidebar_position: 1)
├── installation.md       # Installation (sidebar_position: 2)
├── configuration.md      # Configuration (sidebar_position: 3)
└── deployment.md         # Deployment (sidebar_position: 4)

Each file appears in the sidebar using its title from frontmatter or the first heading.

Custom Ordering

Control order with sidebar_position:

markdown

<!-- docs/guide/deployment.md -->
---
title: Deployment
sidebar_position: 1    # Appears first despite file order
---

markdown

<!-- docs/guide/index.md -->
---
title: Getting Started
sidebar_position: 2    # Appears second
---

Result:

Guide
├── Deployment          (position: 1)
└── Getting Started     (position: 2)

Custom Labels

Override displayed text with sidebar_label:

markdown

---
title: Advanced Configuration Options and Best Practices
sidebar_label: Advanced Config    # Shorter label for sidebar
---

Grouped Auto-generation

Creating Groups

Use _meta.json files to define groups:

docs/guide/
├── _meta.json
├── basics/
│   ├── _meta.json
│   ├── installation.md
│   └── quick-start.md
└── advanced/
    ├── _meta.json
    ├── customization.md
    └── plugins.md

_meta.json Structure

Define group metadata:

json

// docs/guide/_meta.json
{
  "title": "Guide",
  "collapsible": true,
  "collapsed": false,
  "items": {
    "basics": {
      "title": "Getting Started",
      "order": 1
    },
    "advanced": {
      "title": "Advanced Topics",
      "order": 2
    }
  }
}

json

// docs/guide/basics/_meta.json
{
  "title": "Getting Started",
  "items": {
    "installation": {
      "title": "Installation",
      "order": 1
    },
    "quick-start": {
      "title": "Quick Start",
      "order": 2
    }
  }
}

Result

This generates:

Guide
├─ Getting Started
│  ├─ Installation
│  └─ Quick Start
└─ Advanced Topics
   ├─ Customization
   └─ Plugins

Directory-based Groups

Automatic Grouping

Rspress automatically creates groups from directories:

docs/api/
├── cli/
│   ├── dev.md
│   ├── build.md
│   └── preview.md
└── config/
    ├── basic.md
    └── advanced.md

Generates:

API
├─ CLI
│  ├─ dev
│  ├─ build
│  └─ preview
└─ Config
   ├─ basic
   └─ advanced

Group Configuration

Configure groups via frontmatter:

markdown

<!-- docs/api/cli/dev.md -->
---
title: Dev Command
group: CLI Commands
group_order: 1
---

Top-level Directories

Rspress can generate navbar from top-level directories:

typescript

// rspress.config.ts
export default defineConfig({
  themeConfig: {
    nav: 'auto',  // Generate from top-level directories
  },
});

docs/
├── guide/           # → Guide
├── api/             # → API
├── examples/        # → Examples
└── blog/           # → Blog

Customizing Auto-generated Nav

Mix auto-generation with manual items:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      'auto',  // Auto-generate items
      {
        text: 'External',
        link: 'https://example.com',
      },
    ],
  },
});

Mixed Configuration

Combining Auto and Manual

Use both approaches for flexibility:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      // Auto-generate for guide section
      '/guide/': 'auto',

      // Manual config for API section
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'CLI', link: '/api/cli' },
            { text: 'Config', link: '/api/config' },
          ],
        },
      ],

      // Auto-generate for examples
      '/examples/': 'auto',
    },
  },
});

Override Specific Items

Auto-generate with overrides:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': {
        base: 'auto',  // Auto-generate base structure
        override: {
          // Override specific items
          '/guide/advanced': {
            text: 'Advanced Guide',
            collapsible: true,
            collapsed: true,
          },
        },
      },
    },
  },
});

Practical Examples

Example 1: Simple Documentation

docs/
├── index.md
├── installation.md
├── usage.md
└── faq.md

typescript

// rspress.config.ts
export default defineConfig({
  themeConfig: {
    sidebar: {
      '/': 'auto',  // Auto-generate from root
    },
  },
});

Frontmatter:

markdown

<!-- docs/installation.md -->
---
title: Installation
sidebar_position: 1
---

<!-- docs/usage.md -->
---
title: Usage Guide
sidebar_position: 2
---

<!-- docs/faq.md -->
---
title: FAQ
sidebar_position: 3
---

Example 2: Grouped Documentation

docs/
├── getting-started/
│   ├── _meta.json
│   ├── introduction.md
│   ├── installation.md
│   └── quick-start.md
├── guides/
│   ├── _meta.json
│   ├── basic.md
│   └── advanced.md
└── reference/
    ├── _meta.json
    ├── api.md
    └── cli.md

json

// docs/getting-started/_meta.json
{
  "title": "Getting Started",
  "collapsible": true,
  "collapsed": false
}

typescript

// rspress.config.ts
export default defineConfig({
  themeConfig: {
    sidebar: 'auto',  // Auto-generate everything
  },
});

Example 3: Multi-section Site

docs/
├── guide/
│   ├── _meta.json
│   ├── basics/
│   │   ├── intro.md
│   │   └── setup.md
│   └── advanced/
│       ├── custom.md
│       └── plugins.md
├── api/
│   ├── cli.md
│   └── config.md
└── blog/
    ├── 2024-01-post.md
    └── 2024-02-post.md

typescript

// rspress.config.ts
export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: 'Blog', link: '/blog/' },
    ],

    sidebar: {
      '/guide/': 'auto',    // Auto-generate with groups
      '/api/': 'auto',      // Auto-generate flat list
      '/blog/': 'auto',     // Auto-generate chronological
    },
  },
});

Advanced Techniques

Show/hide items based on conditions:

markdown

---
title: Beta Feature
sidebar_position: 10
nav_exclude: true          # Hide from navigation initially
---

Dynamic Ordering

Use numeric prefixes in filenames for ordering:

docs/guide/
├── 01-introduction.md
├── 02-installation.md
├── 03-configuration.md
└── 04-deployment.md

Then strip numbers in frontmatter:

markdown

---
title: Introduction        # No number in title
---

Category Pages

Create index pages for categories:

markdown

<!-- docs/guides/index.md -->
---
title: Guides Overview
sidebar_position: 0        # Appears first in group
---

# Guides

Explore our comprehensive guides:

- [Basic Guide](./basic)
- [Advanced Guide](./advanced)

Troubleshooting

Clear Cache:

bash

rm -rf node_modules/.rspress
npm run dev

Check Frontmatter Syntax:

markdown

---
title: Correct YAML
sidebar_position: 1
---

Verify File Encoding: Ensure UTF-8 encoding

Ordering Issues

Use Consistent Numbering:

markdown

sidebar_position: 1   # Not 1.0 or "1"

Check for Duplicates:

bash

# Search for duplicate positions
grep -r "sidebar_position: 1" docs/

Missing Items

Check File Extension: Must be .md or .mdx
Verify Not Excluded: Check route exclude patterns
Check Frontmatter: Must have valid YAML

markdown

✅ Correct:
---
title: My Page
---

❌ Wrong:
--
title: My Page
--

Performance Considerations

Large Site Optimization

For sites with 100+ pages:

Use Strategic Auto-generation:

typescript

sidebar: {
  '/guide/': 'auto',        // Auto-generate
  '/api/': manualConfig,    // Manual for performance
}

Limit Nesting Depth:

✅ Good: 2-3 levels
docs/
└── guide/
    └── basics/
        └── intro.md

❌ Too Deep: 5+ levels
docs/
└── guide/
    └── learn/
        └── basics/
            └── intro/
                └── getting-started.md

Use Collapsed Groups:

json

{
  "collapsible": true,
  "collapsed": true    // Don't expand by default
}

Best Practices

Frontmatter Standards

Always Include Title:

markdown

---
title: Clear, Descriptive Title
---

Use Consistent Positioning:

markdown

# Leave gaps for future insertions
sidebar_position: 10   # First item
sidebar_position: 20   # Second item
sidebar_position: 30   # Third item

Keep Labels Short:

markdown

---
title: Complete Comprehensive Configuration Guide
sidebar_label: Config Guide    # Shorter for sidebar
---

Directory Structure

Logical Grouping: Group by topic, not file type
Clear Names: Use descriptive directory names
Limit Depth: Maximum 3-4 levels

✅ Good:
docs/
├── getting-started/
├── tutorials/
└── reference/

❌ Confusing:
docs/
├── markdown-files/
├── documentation/
└── pages/

Documentation

Document your navigation structure:

markdown

<!-- docs/README.md -->
# Documentation Structure

## Sidebar Organization

- `/guide/` - Auto-generated from file structure
  - Use `sidebar_position` for ordering
  - Groups defined in `_meta.json`

- `/api/` - Manual configuration
  - Alphabetically ordered
  - See rspress.config.ts

Next Steps

Learn about MDX & React Components
Explore Internationalization for multi-language navigation
Read about Static Assets

Pro Tips

Start with auto-generation, add manual config as needed
Use _meta.json for complex hierarchies
Test navigation on mobile devices
Keep frontmatter consistent across files

Resources

Automatic Navigation Generation ​

Understanding Auto-generation ​

How It Works ​

Benefits ​

Frontmatter Metadata ​

Basic Frontmatter ​

Navigation-specific Fields ​

Complete Frontmatter Reference ​

Sidebar Auto-generation ​

Enable Auto-generation ​

File-based Structure ​

Custom Ordering ​

Custom Labels ​

Grouped Auto-generation ​

Creating Groups ​

_meta.json Structure ​

Result ​

Directory-based Groups ​

Automatic Grouping ​

Group Configuration ​

Navigation Bar Auto-generation ​

Top-level Directories ​

Customizing Auto-generated Nav ​

Mixed Configuration ​

Combining Auto and Manual ​

Override Specific Items ​

Practical Examples ​

Example 1: Simple Documentation ​

Example 2: Grouped Documentation ​

Example 3: Multi-section Site ​

Advanced Techniques ​

Conditional Navigation ​

Dynamic Ordering ​

Category Pages ​

Troubleshooting ​

Navigation Not Updating ​

Ordering Issues ​

Missing Items ​

Performance Considerations ​

Large Site Optimization ​

Best Practices ​

Frontmatter Standards ​

Directory Structure ​

Documentation ​

Next Steps ​

Automatic Navigation Generation

Understanding Auto-generation

How It Works

Benefits

Frontmatter Metadata

Basic Frontmatter

Navigation-specific Fields

Complete Frontmatter Reference

Sidebar Auto-generation

Enable Auto-generation

File-based Structure

Custom Ordering

Custom Labels

Grouped Auto-generation

Creating Groups

_meta.json Structure

Result

Directory-based Groups

Automatic Grouping

Group Configuration

Navigation Bar Auto-generation

Top-level Directories

Customizing Auto-generated Nav

Mixed Configuration

Combining Auto and Manual

Override Specific Items

Practical Examples

Example 1: Simple Documentation

Example 2: Grouped Documentation

Example 3: Multi-section Site

Advanced Techniques

Conditional Navigation

Dynamic Ordering

Category Pages

Troubleshooting

Navigation Not Updating

Ordering Issues

Missing Items

Performance Considerations

Large Site Optimization

Best Practices

Frontmatter Standards

Directory Structure

Documentation

Next Steps