如何在Docusaurus V2自动生成侧边栏中隐藏index条目

开发者阿泽

2026-8-29

Docusaurus v2 自动侧边栏冗余index条目问题解决方案

1. 隐藏自动生成侧边栏中冗余index条目的正确配置

直接在autogenerated配置项顶层添加exclude触发报错，是因为Docusaurus v2稳定版的autogenerated侧边栏不存在该顶层配置项，可通过以下两种方式实现隐藏：

方案一：通过文件frontmatter标记隐藏
打开需要隐藏的空index.md文件，在文件头部添加如下frontmatter字段：
```
---
sidebar_custom_props:
  hidden: true
---
```
配置后自动生成侧边栏时会直接跳过该文件，不生成对应导航条目，同时保留文件路由，不会破坏原有页面加载逻辑。

方案二：自定义侧边栏生成逻辑过滤条目
修改sidebar.js配置，通过自定义sidebarItemsGenerator方法过滤目标index条目，参考配置如下：

module.exports = {
  docs: [
    {
      type: 'autogenerated',
      dirName: '.',
      sidebarItemsGenerator: async ({defaultSidebarItemsGenerator, ...args}) => {
        const defaultItems = await defaultSidebarItemsGenerator(args);
        // 此处id替换为目标index文件的实际id，通常为文件相对于docs目录的无后缀路径
        return defaultItems.filter(item => item.id !== 'index');
      }
    },
  ],
};

2. 移除空index.md依赖的可行配置方案

完全可以不依赖空index.md文件保障页面加载，通过分类配置即可实现：

删除所有仅用于路由承接的空index.md文件
在每个顶层分类文件夹下新建_category_.json配置文件，指定分类的跳转链接指向分类下的实际有效文档，参考配置如下：
```
{
  "label": "分类展示名称",
  "position": 2,
  "link": {
    "type": "doc",
    "id": "该分类下要作为默认首页的文档id"
  }
}
```
如果存在原有指向index路径的访问需求，可在docusaurus.config.js的docs插件配置中添加重定向规则，将旧路径跳转到对应有效文档即可。