Docusaurus中复杂分类类型的侧边栏简写方案问询

情况是否属实？ #

没错，这个情况是属实的。Docusaurus 的 sidebar 配置中，仅单个文档项支持简写（直接写文档 ID 字符串），但对于 doc 类型的显式链接配置、generated-index 这类特殊分类项，必须使用完整的对象结构，官方并没有提供对应的简写语法。

解决办法 #

1. 自定义转换函数简化配置 #

自己写一个工具函数，把你想要的简写格式自动转换成符合 Docusaurus 要求的完整配置对象，这样就能在配置里用简写，再通过函数处理成标准格式。

示例代码：

// sidebar.js 中定义转换函数
function parseSidebarItem(item) {
  // 处理文档链接简写：字符串转 {type: 'doc', id: xxx}
  if (typeof item === 'string') {
    return { type: 'doc', id: item };
  }
  // 处理 generated-index 的简化配置（自动补全默认标题）
  if (item.type === 'generated-index' && !item.title) {
    return { ...item, title: '目录索引' };
  }
  // 嵌套分类的 items 递归处理
  if (item.items) {
    return { ...item, items: item.items.map(parseSidebarItem) };
  }
  return item;
}

// 最终导出的侧边栏配置
module.exports = {
  mainSidebar: [
    // 直接用字符串简写文档链接
    parseSidebarItem('intro'),
    {
      type: 'category',
      label: '核心指南',
      items: [
        'getting-started',
        'advanced-usage',
        // 直接写 generated-index 的简化配置
        { type: 'generated-index', description: '所有指南内容汇总' }
      ].map(parseSidebarItem)
    }
  ]
};

2. 封装配置片段 #

把常用的 generated-index 或 doc 配置做成可复用的片段，减少重复代码。比如：

// 定义复用片段
const genIndex = (desc) => ({
  type: 'generated-index',
  title: '内容索引',
  description: desc
});

const docLink = (id) => ({ type: 'doc', id });

// 使用时直接调用
module.exports = {
  mainSidebar: [
    docLink('intro'),
    {
      type: 'category',
      label: 'API 文档',
      items: [
        docLink('api/auth'),
        genIndex('所有 API 接口汇总'),
        docLink('api/storage')
      ]
    }
  ]
};

3. 社区插件扩展（可选） #

部分社区插件会扩展 Docusaurus 的侧边栏配置能力，支持更灵活的简写语法。你可以在项目依赖中搜索相关插件，自定义配置规则来匹配你的需求。

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