导航栏与侧边栏配置

良好的导航系统对文档网站至关重要。Rspress 为顶部导航栏和侧边栏提供了灵活的配置选项,帮助用户高效地浏览您的内容。

导航栏配置

基本导航栏

在 rspress.config.ts 中配置导航栏:

typescript

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

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: '首页',
        link: '/',
      },
      {
        text: '指南',
        link: '/guide/',
      },
      {
        text: 'API',
        link: '/api/',
      },
    ],
  },
});

下拉菜单

为分组导航项创建下拉菜单:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: '文档',
        items: [
          {
            text: '快速开始',
            link: '/guide/getting-started',
          },
          {
            text: '配置',
            link: '/guide/configuration',
          },
          {
            text: '部署',
            link: '/guide/deployment',
          },
        ],
      },
      {
        text: '资源',
        items: [
          {
            text: '示例',
            link: '/examples/',
          },
          {
            text: '更新日志',
            link: '/changelog',
          },
        ],
      },
    ],
  },
});

多级下拉菜单

创建嵌套下拉结构:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: '学习',
        items: [
          {
            text: '基础',
            items: [
              { text: '介绍', link: '/basics/introduction' },
              { text: '快速开始', link: '/basics/quick-start' },
            ],
          },
          {
            text: '进阶',
            items: [
              { text: '定制化', link: '/advanced/customization' },
              { text: '插件', link: '/advanced/plugins' },
            ],
          },
        ],
      },
    ],
  },
});

外部链接

添加带自动图标指示器的外部链接:

typescript

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

激活状态

导航项根据当前路由自动高亮:

typescript

// 当当前路由以链接开头时激活
{
  text: '指南',
  link: '/guide/',
  // 对 /guide/, /guide/start, /guide/config 高亮
}

// 仅精确匹配
{
  text: '首页',
  link: '/',
  activeMatch: '^/$',  // 仅对首页激活
}

侧边栏配置

基本侧边栏

为特定路由路径配置侧边栏:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '快速开始',
          link: '/guide/',
        },
        {
          text: '安装',
          link: '/guide/installation',
        },
        {
          text: '配置',
          link: '/guide/configuration',
        },
      ],
    },
  },
});

分组侧边栏项

将侧边栏项组织成可折叠的组:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '介绍',
          items: [
            {
              text: '什么是 Rspress?',
              link: '/guide/',
            },
            {
              text: '为什么选择 Rspress?',
              link: '/guide/why',
            },
          ],
        },
        {
          text: '快速开始',
          items: [
            {
              text: '安装',
              link: '/guide/installation',
            },
            {
              text: '快速入门',
              link: '/guide/quick-start',
            },
          ],
        },
        {
          text: '高级主题',
          items: [
            {
              text: '定制化',
              link: '/guide/customization',
            },
            {
              text: '插件开发',
              link: '/guide/plugins',
            },
          ],
        },
      ],
    },
  },
});

可折叠组

控制组的折叠行为:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '基础',
          collapsible: true,        // 可以折叠
          collapsed: false,         // 默认展开
          items: [
            { text: '介绍', link: '/guide/intro' },
            { text: '安装', link: '/guide/install' },
          ],
        },
        {
          text: '进阶',
          collapsible: true,
          collapsed: true,          // 默认折叠
          items: [
            { text: '定制化', link: '/guide/custom' },
            { text: '插件', link: '/guide/plugins' },
          ],
        },
      ],
    },
  },
});

多个侧边栏

为不同部分定义不同的侧边栏:

typescript

export default defineConfig({
  themeConfig: {
    sidebar: {
      // 指南部分侧边栏
      '/guide/': [
        {
          text: '指南',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '快速开始', link: '/guide/start' },
          ],
        },
      ],

      // API 部分侧边栏
      '/api/': [
        {
          text: 'API 参考',
          items: [
            { text: 'CLI', link: '/api/cli' },
            { text: '配置', link: '/api/config' },
            { text: '插件 API', link: '/api/plugin' },
          ],
        },
      ],

      // 示例部分侧边栏
      '/examples/': [
        {
          text: '示例',
          items: [
            { text: '基础用法', link: '/examples/basic' },
            { text: '高级功能', link: '/examples/advanced' },
          ],
        },
      ],
    },
  },
});

社交链接

向导航添加社交媒体和社区链接:

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

自定义图标

为社交链接使用自定义 SVG 图标:

typescript

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

Logo 配置

基本 Logo

设置您的网站 Logo:

typescript

export default defineConfig({
  logo: '/logo.png',
  themeConfig: {
    // Logo 出现在导航栏中
  },
});

支持深色模式的 Logo

为浅色和深色主题提供不同的 Logo:

typescript

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

带链接的 Logo

使 Logo 可点击:

typescript

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

高级导航功能

版本选择器

添加版本选择下拉菜单:

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'v2.0.0',
        items: [
          {
            text: 'v2.0.0 (最新)',
            link: '/v2/',
          },
          {
            text: 'v1.5.0',
            link: '/v1/',
          },
          {
            text: '发布说明',
            link: '/changelog',
          },
        ],
      },
    ],
  },
});

搜索集成

Rspress 包含与导航集成的内置搜索:

typescript

export default defineConfig({
  search: {
    // 搜索默认启用
    // 自动出现在导航栏中
  },
  themeConfig: {
    // 导航项与搜索并排出现
  },
});

响应式行为

移动端导航

导航自动适配移动设备:

小屏幕上显示汉堡菜单
侧边栏从左侧滑入
触摸友好的交互

typescript

// 移动端行为是自动的
// 不需要额外配置
export default defineConfig({
  themeConfig: {
    nav: [
      // 这些在移动端也能正常工作
    ],
  },
});

本地化导航

每种语言的导航

为每种语言配置不同的导航:

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

实践示例

示例 1: 文档站点

typescript

export default defineConfig({
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/api/' },
      {
        text: 'v2.0.0',
        items: [
          { text: '更新日志', link: '/changelog' },
          { text: 'v1.x 文档', link: '/v1/' },
        ],
      },
    ],

    sidebar: {
      '/guide/': [
        {
          text: '介绍',
          items: [
            { text: '什么是 Rspress?', link: '/guide/' },
            { text: '快速开始', link: '/guide/start' },
          ],
        },
        {
          text: '核心概念',
          items: [
            { text: '路由', link: '/guide/routing' },
            { text: '导航', link: '/guide/navigation' },
            { text: 'MDX', link: '/guide/mdx' },
          ],
        },
        {
          text: '进阶',
          collapsible: true,
          collapsed: true,
          items: [
            { text: '定制化', link: '/guide/customization' },
            { text: '插件', link: '/guide/plugins' },
            { text: '主题', link: '/guide/theming' },
          ],
        },
      ],

      '/api/': [
        {
          text: 'API 参考',
          items: [
            { text: 'CLI', link: '/api/cli' },
            { text: '配置', link: '/api/config' },
            { text: '插件 API', link: '/api/plugin' },
            { text: '主题 API', link: '/api/theme' },
          ],
        },
      ],
    },

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

最佳实践

导航结构

限制顶级项目: 最多 5-7 个主导航项
使用有意义的标签: 清晰、简洁的文本描述内容
逻辑分组: 将相关项组织在一起
一致的命名: 在整个过程中使用一致的术语

typescript

✅ 好的做法:
nav: [
  { text: '指南', link: '/guide/' },
  { text: 'API', link: '/api/' },
  { text: '示例', link: '/examples/' },
]

❌ 太多:
nav: [
  { text: '首页', link: '/' },
  { text: '指南', link: '/guide/' },
  { text: '教程', link: '/tutorial/' },
  { text: 'API', link: '/api/' },
  { text: 'CLI', link: '/cli/' },
  { text: '配置', link: '/config/' },
  { text: '示例', link: '/examples/' },
  { text: 'FAQ', link: '/faq/' },
]

侧边栏组织

渐进式展示: 从简单开始,逐步揭示复杂性
按主题分组: 不是按文件类型或技术结构
限制深度: 最多 2-3 层
一致的顺序: 遵循学习进程或逻辑顺序

typescript

✅ 好的组织:
sidebar: {
  '/guide/': [
    {
      text: '快速开始',  // 从这里开始
      items: [...]
    },
    {
      text: '核心概念',    // 然后学习概念
      items: [...]
    },
    {
      text: '进阶',         // 最后是高级主题
      items: [...]
    },
  ],
}

下一步

学习自动导航生成
探索MDX 及 React 组件
了解国际化实现多语言导航

设计技巧

在导航文本中谨慎使用图标
确保足够的对比度以提高可访问性
在移动设备上测试导航
保持标签简短 (1-3 个词最理想)

常见错误

不要创建太多嵌套下拉层级
避免在导航和侧边栏中出现重复链接
不要将重要页面隐藏在导航深处
记得在添加新页面时更新导航

导航栏与侧边栏配置 ​

导航栏配置 ​

基本导航栏 ​

下拉菜单 ​

多级下拉菜单 ​

外部链接 ​

激活状态 ​

侧边栏配置 ​

基本侧边栏 ​

分组侧边栏项 ​

可折叠组 ​

多个侧边栏 ​

社交链接 ​

自定义图标 ​

Logo 配置 ​

基本 Logo ​

支持深色模式的 Logo ​

带链接的 Logo ​

高级导航功能 ​

版本选择器 ​

搜索集成 ​

响应式行为 ​

移动端导航 ​

本地化导航 ​

每种语言的导航 ​

实践示例 ​

示例 1: 文档站点 ​

最佳实践 ​

导航结构 ​

侧边栏组织 ​

下一步 ​

导航栏与侧边栏配置

导航栏配置

基本导航栏

下拉菜单

多级下拉菜单

外部链接

激活状态

侧边栏配置

基本侧边栏

分组侧边栏项

可折叠组

多个侧边栏

社交链接

自定义图标

Logo 配置

基本 Logo

支持深色模式的 Logo

带链接的 Logo

高级导航功能

版本选择器

搜索集成

响应式行为

移动端导航

本地化导航

每种语言的导航

实践示例

示例 1: 文档站点

最佳实践

导航结构

侧边栏组织

下一步