Kenhuang Academy
  • English

      • 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.

      Basic Navigation Bar

      Configure the navigation bar in rspress.config.ts:

      // 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:

      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',
          },
        ],
      },
    ],
  },
});

      Multi-level Dropdown

      Create nested dropdown structures:

      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' },
            ],
          },
        ],
      },
    ],
  },
});

      Add external links with automatic icon indicators:

      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:

      // 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
}

      Basic Sidebar

      Configure sidebar for specific route paths:

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

      Grouped Sidebar Items

      Organize sidebar items into collapsible groups:

      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:

      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:

      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:

      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:

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

      Logo Configuration

      Set your site logo:

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

      Logo with Dark Mode Support

      Provide different logos for light and dark themes:

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

      Make the logo clickable:

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

      Advanced Navigation Features

      Version Selector

      Add version selection dropdown:

      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:

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

      Custom Navigation Order

      Control the order of navigation elements:

      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

      Mobile Navigation

      Navigation automatically adapts for mobile devices:

      • Hamburger menu on small screens
      • Sidebar slides in from left
      • Touch-friendly interactions
      // Mobile behavior is automatic
// No additional configuration needed
export default defineConfig({
  themeConfig: {
    nav: [
      // These work on mobile too
    ],
  },
});

      Hide Navigation Elements

      Hide specific elements on mobile:

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

      Localized Navigation

      Per-language Navigation

      Configure different navigation for each language:

      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

      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

      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

      1. Keep Top-Level Items Limited: 5-7 main navigation items maximum
      2. Use Meaningful Labels: Clear, concise text that describes content
      3. Logical Grouping: Group related items together
      4. Consistent Naming: Use consistent terminology throughout
      ✅ 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/' },
]
      1. Progressive Disclosure: Start simple, reveal complexity gradually
      2. Group by Topic: Not by file type or technical structure
      3. Limit Depth: 2-3 levels maximum
      4. Consistent Order: Follow learning progression or logical sequence
      ✅ 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:

      # 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

      ::: tip 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) :::

      ::: warning 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 :::