Navigation Bar and Sidebar Configuration

A well-structured navigation system is crucial for documentation sites. Rspress provides flexible configuration options for both the top navigation bar and sidebar, helping users navigate your content efficiently.

Configure the navigation bar in rspress.config.ts:

typescript

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

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Home',
        link: '/',
      },
      {
        text: 'Guide',
        link: '/guide/',
      },
      {
        text: 'API',
        link: '/api/',
      },
    ],
  },
});

Create dropdown menus for grouped navigation items:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Documentation',
        items: [
          {
            text: 'Getting Started',
            link: '/guide/getting-started',
          },
          {
            text: 'Configuration',
            link: '/guide/configuration',
          },
          {
            text: 'Deployment',
            link: '/guide/deployment',
          },
        ],
      },
      {
        text: 'Resources',
        items: [
          {
            text: 'Examples',
            link: '/examples/',
          },
          {
            text: 'Changelog',
            link: '/changelog',
          },
        ],
      },
    ],
  },
});

Create nested dropdown structures:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Learn',
        items: [
          {
            text: 'Basics',
            items: [
              { text: 'Introduction', link: '/basics/introduction' },
              { text: 'Quick Start', link: '/basics/quick-start' },
            ],
          },
          {
            text: 'Advanced',
            items: [
              { text: 'Customization', link: '/advanced/customization' },
              { text: 'Plugins', link: '/advanced/plugins' },
            ],
          },
        ],
      },
    ],
  },
});

External Links

Add external links with automatic icon indicators:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'GitHub',
        link: 'https://github.com/web-infra-dev/rspress',
      },
      {
        text: 'Discord',
        link: 'https://discord.gg/rspack-rspress',
      },
    ],
  },
});

Active State

Navigation items automatically highlight based on current route:

typescript

// Active when current route starts with the link
{
  text: 'Guide',
  link: '/guide/',
  // Highlights for: /guide/, /guide/start, /guide/config
}

// Exact match only
{
  text: 'Home',
  link: '/',
  activeMatch: '^/$',  // Active only for homepage
}

Configure sidebar for specific route paths:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          link: '/guide/',
        },
        {
          text: 'Installation',
          link: '/guide/installation',
        },
        {
          text: 'Configuration',
          link: '/guide/configuration',
        },
      ],
    },
  },
});

Organize sidebar items into collapsible groups:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Introduction',
          items: [
            {
              text: 'What is Rspress?',
              link: '/guide/',
            },
            {
              text: 'Why Rspress?',
              link: '/guide/why',
            },
          ],
        },
        {
          text: 'Getting Started',
          items: [
            {
              text: 'Installation',
              link: '/guide/installation',
            },
            {
              text: 'Quick Start',
              link: '/guide/quick-start',
            },
          ],
        },
        {
          text: 'Advanced Topics',
          items: [
            {
              text: 'Customization',
              link: '/guide/customization',
            },
            {
              text: 'Plugin Development',
              link: '/guide/plugins',
            },
          ],
        },
      ],
    },
  },
});

Collapsible Groups

Control group collapse behavior:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Basic',
          collapsible: true,        // Can be collapsed
          collapsed: false,         // Expanded by default
          items: [
            { text: 'Introduction', link: '/guide/intro' },
            { text: 'Installation', link: '/guide/install' },
          ],
        },
        {
          text: 'Advanced',
          collapsible: true,
          collapsed: true,          // Collapsed by default
          items: [
            { text: 'Customization', link: '/guide/custom' },
            { text: 'Plugins', link: '/guide/plugins' },
          ],
        },
      ],
    },
  },
});

Multiple Sidebars

Define different sidebars for different sections:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      // Guide section sidebar
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Introduction', link: '/guide/' },
            { text: 'Getting Started', link: '/guide/start' },
          ],
        },
      ],

      // API section sidebar
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'CLI', link: '/api/cli' },
            { text: 'Config', link: '/api/config' },
            { text: 'Plugin API', link: '/api/plugin' },
          ],
        },
      ],

      // Examples section sidebar
      '/examples/': [
        {
          text: 'Examples',
          items: [
            { text: 'Basic Usage', link: '/examples/basic' },
            { text: 'Advanced Features', link: '/examples/advanced' },
          ],
        },
      ],
    },
  },
});

Add social media and community links to the navigation:

typescript

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/web-infra-dev/rspress',
      },
      {
        icon: 'discord',
        mode: 'link',
        content: 'https://discord.gg/rspack-rspress',
      },
      {
        icon: 'twitter',
        mode: 'link',
        content: 'https://twitter.com/rspack_dev',
      },
      {
        icon: 'wechat',
        mode: 'qrcode',
        content: '/qrcode-wechat.png',
      },
    ],
  },
});

Custom Icons

Use custom SVG icons for social links:

typescript

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: {
          svg: '<svg>...</svg>',  // Your custom SVG
        },
        mode: 'link',
        content: 'https://example.com',
      },
    ],
  },
});

Logo Configuration

Basic Logo

Set your site logo:

typescript

export default defineConfig({
  logo: '/logo.png',
  themeConfig: {
    // Logo appears in navbar
  },
});

Logo with Dark Mode Support

Provide different logos for light and dark themes:

typescript

export default defineConfig({
  logo: {
    light: '/logo-light.png',
    dark: '/logo-dark.png',
  },
});

Logo with Link

Make the logo clickable:

typescript

export default defineConfig({
  logo: {
    light: '/logo-light.png',
    dark: '/logo-dark.png',
  },
  logoLink: '/',  // Default is '/'
});

Version Selector

Add version selection dropdown:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'v2.0.0',
        items: [
          {
            text: 'v2.0.0 (Latest)',
            link: '/v2/',
          },
          {
            text: 'v1.5.0',
            link: '/v1/',
          },
          {
            text: 'Release Notes',
            link: '/changelog',
          },
        ],
      },
    ],
  },
});

Search Integration

Rspress includes built-in search that integrates with navigation:

typescript

export default defineConfig({
  search: {
    // Search is enabled by default
    // Automatically appears in navbar
  },
  themeConfig: {
    // Navigation items appear alongside search
  },
});

Control the order of navigation elements:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },        // First
      { text: 'Guide', link: '/guide/' }, // Second
      { text: 'API', link: '/api/' },     // Third
      // Social links appear after nav items
    ],
  },
});

Responsive Behavior

Navigation automatically adapts for mobile devices:

Hamburger menu on small screens
Sidebar slides in from left
Touch-friendly interactions

typescript

// Mobile behavior is automatic
// No additional configuration needed
export default defineConfig({
  themeConfig: {
    nav: [
      // These work on mobile too
    ],
  },
});

Hide specific elements on mobile:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Advanced Topics',
          // This group is always visible
          items: [...],
        },
      ],
    },
  },
});

Configure different navigation for each language:

typescript

export default defineConfig({
  locales: [
    {
      lang: 'en',
      label: 'English',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/' },
          { text: 'Guide', link: '/guide/' },
        ],
      },
    },
    {
      lang: 'zh',
      label: '简体中文',
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '指南', link: '/zh/guide/' },
        ],
      },
    },
  ],
});

Practical Examples

Example 1: Documentation Site

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      {
        text: 'v2.0.0',
        items: [
          { text: 'Changelog', link: '/changelog' },
          { text: 'v1.x Docs', link: '/v1/' },
        ],
      },
    ],

    sidebar: {
      '/guide/': [
        {
          text: 'Introduction',
          items: [
            { text: 'What is Rspress?', link: '/guide/' },
            { text: 'Getting Started', link: '/guide/start' },
          ],
        },
        {
          text: 'Core Concepts',
          items: [
            { text: 'Routing', link: '/guide/routing' },
            { text: 'Navigation', link: '/guide/navigation' },
            { text: 'MDX', link: '/guide/mdx' },
          ],
        },
        {
          text: 'Advanced',
          collapsible: true,
          collapsed: true,
          items: [
            { text: 'Customization', link: '/guide/customization' },
            { text: 'Plugins', link: '/guide/plugins' },
            { text: 'Theming', link: '/guide/theming' },
          ],
        },
      ],

      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'CLI', link: '/api/cli' },
            { text: 'Config', link: '/api/config' },
            { text: 'Plugin API', link: '/api/plugin' },
            { text: 'Theme API', link: '/api/theme' },
          ],
        },
      ],
    },

    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/example/docs',
      },
    ],
  },
});

Example 2: Component Library Docs

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Components', link: '/components/' },
      { text: 'Design', link: '/design/' },
      {
        text: 'Resources',
        items: [
          { text: 'Examples', link: '/examples/' },
          { text: 'Playground', link: '/playground' },
        ],
      },
    ],

    sidebar: {
      '/components/': [
        {
          text: 'Basic',
          items: [
            { text: 'Button', link: '/components/button' },
            { text: 'Input', link: '/components/input' },
            { text: 'Select', link: '/components/select' },
          ],
        },
        {
          text: 'Layout',
          items: [
            { text: 'Grid', link: '/components/grid' },
            { text: 'Container', link: '/components/container' },
          ],
        },
        {
          text: 'Data Display',
          items: [
            { text: 'Table', link: '/components/table' },
            { text: 'Card', link: '/components/card' },
          ],
        },
      ],
    },
  },
});

Best Practices

Keep Top-Level Items Limited: 5-7 main navigation items maximum
Use Meaningful Labels: Clear, concise text that describes content
Logical Grouping: Group related items together
Consistent Naming: Use consistent terminology throughout

typescript

✅ Good:
nav: [
  { text: 'Guide', link: '/guide/' },
  { text: 'API', link: '/api/' },
  { text: 'Examples', link: '/examples/' },
]

❌ Too Many:
nav: [
  { text: 'Home', link: '/' },
  { text: 'Guide', link: '/guide/' },
  { text: 'Tutorial', link: '/tutorial/' },
  { text: 'API', link: '/api/' },
  { text: 'CLI', link: '/cli/' },
  { text: 'Config', link: '/config/' },
  { text: 'Examples', link: '/examples/' },
  { text: 'FAQ', link: '/faq/' },
]

Progressive Disclosure: Start simple, reveal complexity gradually
Group by Topic: Not by file type or technical structure
Limit Depth: 2-3 levels maximum
Consistent Order: Follow learning progression or logical sequence

typescript

✅ Good Organization:
sidebar: {
  '/guide/': [
    {
      text: 'Getting Started',  // Begin here
      items: [...]
    },
    {
      text: 'Core Concepts',    // Then learn concepts
      items: [...]
    },
    {
      text: 'Advanced',         // Finally advanced topics
      items: [...]
    },
  ],
}

Active States

Test that active states work correctly:

bash

# Visit these URLs and check highlighting
http://localhost:5173/
http://localhost:5173/guide/
http://localhost:5173/guide/start
http://localhost:5173/api/config

Next Steps

Learn about Automatic Navigation Generation
Explore MDX & React Components
Read about Internationalization for multi-language navigation

Design Tips

Use icons sparingly in navigation text
Ensure sufficient contrast for accessibility
Test navigation on mobile devices
Keep labels short (1-3 words ideal)

Common Mistakes

Don't create too many nested dropdown levels
Avoid duplicate links in navigation and sidebar
Don't hide important pages deep in navigation
Remember to update navigation when adding new pages

Navigation Bar and Sidebar Configuration

Navigation Bar Configuration

Basic Navigation Bar

External Links

Active State

Sidebar Configuration

Basic Sidebar

Grouped Sidebar Items

Collapsible Groups

Multiple Sidebars

Custom Icons

Logo Configuration

Basic Logo

Logo with Dark Mode Support

Logo with Link

Advanced Navigation Features

Version Selector

Search Integration

Custom Navigation Order

Responsive Behavior

Mobile Navigation

Hide Navigation Elements

Localized Navigation

Per-language Navigation

Practical Examples

Example 1: Documentation Site

Example 2: Component Library Docs

Best Practices

Navigation Structure

Sidebar Organization

Active States

Next Steps

Navigation Bar and Sidebar Configuration ​

Navigation Bar Configuration ​

Basic Navigation Bar ​

Dropdown Menu ​

Multi-level Dropdown ​

External Links ​

Active State ​

Sidebar Configuration ​

Basic Sidebar ​

Grouped Sidebar Items ​

Collapsible Groups ​

Multiple Sidebars ​

Social Links ​

Custom Icons ​

Logo Configuration ​

Basic Logo ​

Logo with Dark Mode Support ​

Logo with Link ​

Advanced Navigation Features ​

Version Selector ​

Search Integration ​

Custom Navigation Order ​

Responsive Behavior ​

Mobile Navigation ​

Hide Navigation Elements ​

Localized Navigation ​

Per-language Navigation ​

Practical Examples ​

Example 1: Documentation Site ​

Example 2: Component Library Docs ​

Best Practices ​

Navigation Structure ​

Sidebar Organization ​

Active States ​

Next Steps ​

Navigation Bar and Sidebar Configuration

Navigation Bar Configuration

Basic Navigation Bar

Dropdown Menu

Multi-level Dropdown

External Links

Active State

Sidebar Configuration

Basic Sidebar

Grouped Sidebar Items

Collapsible Groups

Multiple Sidebars

Social Links

Custom Icons

Logo Configuration

Basic Logo

Logo with Dark Mode Support

Logo with Link

Advanced Navigation Features

Version Selector

Search Integration

Custom Navigation Order

Responsive Behavior

Mobile Navigation

Hide Navigation Elements

Localized Navigation

Per-language Navigation

Practical Examples

Example 1: Documentation Site

Example 2: Component Library Docs

Best Practices

Navigation Structure

Sidebar Organization

Active States

Next Steps