侧边栏与导航

配置文件

侧边栏由根目录 sidebars.ts 定义，导出名为 docs 的配置对象，与 docusaurus.config.ts 中 sidebarId: 'docs' 对应。

结构说明

常用 sidebar 项类型

单文档

'intro',
'systems/cssadoc/index',

字符串即 doc ID，对应 docs/ 下相对路径（无扩展名）。

分类（可折叠）

{
  type: 'category',
  label: 'CSSA GPT',
  key: 'cssagpt',           // 可选，用于 i18n 与折叠状态
  items: [
    'systems/cssagpt/index',
    // ...
  ],
},

带自定义标签的单文档

{
  type: 'doc',
  id: 'systems/cssagpt/FAQ',
  label: '常见问题',
  key: 'cssagpt-faq',
},

添加新页面到导航

1. 确认 doc ID（文件路径去掉 docs/ 与 .md）
2. 在对应 category.items 数组中追加 ID 或嵌套 category
3. 保存后重启 dev server 或重新 build

排序

• 分类顺序：由 items 数组顺序决定
• 同目录文档顺序：可在 frontmatter 设置 sidebar_position（数字越小越靠前）
• 系统首页：通常 sidebar_position: 0

版本与 i18n

• 文档版本：versioned_docs/version-v1/ 存放 V1 快照；切换版本时 sidebar 指向对应版本内容
• 侧边栏翻译：i18n/zh-Hans/docusaurus-plugin-content-docs/current.json 等文件中可覆盖 category label

常见错误

• ❌ doc ID 大小写或路径拼写错误 → 构建报 doc not found
• ❌ 同一 doc ID 重复注册 → 侧边栏出现重复项
• ❌ 修改 sidebars.ts 后未重启 dev server，看不到变化