Docusaurus多文档实例导航栏链接均指向同一份intro.md问题求助

问题根因 #

两个问题均由多实例关联配置不匹配导致，核心是未显式指定文档实例与导航项的绑定关系，以及缺少必填的实例唯一标识配置。

修复步骤 #

1. 确认实例配置必填项 #

在docusaurus.config.js中，默认preset携带的文档实例id默认为default，新增的开发文档实例必须配置唯一id、本地目录映射、访问路由前缀，示例配置如下：

module.exports = {
  // 其余全局配置省略
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'dev', // 唯一标识，不可与默认实例重名
        path: 'dev', // 映射本地存放开发文档的/dev目录
        routeBasePath: 'dev', // 访问路径前缀，所有开发文档路由均携带/dev前缀
        sidebarPath: require.resolve('./sidebarsDev.js'), // 单独配置开发文档侧边栏文件，避免与默认文档冲突
      },
    ],
  ],
}

2. 修正导航栏绑定配置 #

导航栏的doc类型条目必须显式指定docsPluginId参数关联对应实例，否则默认全部指向id为default的默认文档实例，示例配置如下：

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        // 面向创作者的默认文档导航
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: '创作者手册',
          docsPluginId: 'default', // 关联默认文档实例
        },
        // 开发文档导航
        {
          type: 'doc',
          docId: 'devintro',
          position: 'left',
          label: '开发文档',
          docsPluginId: 'dev', // 关联新增的dev文档实例
        },
      ]
    }
  }
}

3. 侧边栏与缓存校验 #

• 新增sidebarsDev.js文件，侧边栏条目配置仅对应/dev目录下的文档文件名
• 执行npm run clear清理本地缓存后重启开发服务，避免旧配置缓存导致异常

问题对应说明 #

1. 两个导航都指向/docs/intro：未给导航项加docsPluginId，默认全部匹配默认实例下的文档
2. 重命名后页面空白：要么实例未配置routeBasePath导致路由冲突，要么侧边栏/导航的docId与/dev目录下的文件名不匹配，要么缓存未清理

内容的提问来源于stack exchange，提问作者Jenny