跳到主要内容

创建专题目录工作流

这篇文档约束这个仓库以后新增专题目录的标准方式。

目标效果是：

  • 左侧侧边栏点击专题时，先进入专题索引页，而不是直接跳到第一篇文章
  • 专题页自动列出该目录下的全部文章，效果与 docs/DataStructer/sorting-algorithms 一致
  • 前端显示中文名称，但目录名、文件名和浏览器链接保持英文稳定路径

如果以后继续往 docs/SuperComputer、docs/DataStructer、docs/Python 这类板块里增加新的专题目录，默认以这篇文档为准。

先看两个现成范例​

  • 数据结构里的 docs/DataStructer/sorting-algorithms
  • 超算里的 docs/SuperComputer/slurm-scheduler-system

它们现在都满足同一种行为：

  • 侧边栏里显示的是中文专题名
  • 点击专题后先进入一个自动生成的专题索引页
  • 专题索引页会列出这个专题下的文章

核心原则​

1. 想要“点击专题先看到索引页”，就必须用 generated-index​

专题目录的 _category_.json 必须写成：

  • link.type: "generated-index"

不要写成：

  • link.type: "doc"

doc 会把专题点击行为绑定到某一篇具体文档，不是我们要的效果。

2. 这种专题目录不要再手写 index.mdx​

如果目标是“像排序算法那样自动展示专题下文章列表”，就不要再在专题目录里写一个 index.mdx 充当首页。

原因很直接：

  • generated-index 本身就会生成专题页
  • 手写 index.mdx 很容易占用同一条路由
  • 一旦路由被占用，点击专题时就会进入你手写的文档页，而不是自动索引页

3. 目录名和文件名用英文，显示名用中文​

以后新增专题目录时，默认使用下面这套约定：

  • 目录名：英文 kebab-case
  • 文件名：英文 kebab-case
  • 专题显示名：在 _category_.json 的 label 里写中文
  • 文章标题：用文档里的 # H1 写中文

例如：

docs/SuperComputer/slurm-scheduler-system/
docs/SuperComputer/slurm-scheduler-system/slurm-basic-usage.mdx

显示时可以是：

  • Slurm调度系统
  • SLURM调度系统的基础使用

但浏览器路径仍然保持英文。

4. front matter 只保留必要字段​

这类专题下的普通文章，默认不要写一堆重复 front matter。

优先保留：

  • sidebar_position

按需保留：

  • slug：只有当路径必须和文件名解耦时才写
  • sidebar_label：只有当侧边栏名称必须和 H1 不同时才写
  • title / description：只有确实需要覆盖自动推导时才写

如果 H1、文件名和路径本来就合理，就不要重复写同一份信息。

标准流程​

第一步：创建专题目录​

目录放到对应板块下：

docs/<Section>/<topic-dir>/

例如：

docs/SuperComputer/slurm-scheduler-system/
docs/DataStructer/sorting-algorithms/

第二步：创建 _category_.json​

专题目录里必须有一个 _category_.json。

标准模板：

{
  "label": "专题中文名",
  "position": 0,
  "link": {
    "type": "generated-index",
    "slug": "/category/topic-slug",
    "description": "这里写这个专题的简短说明。"
  }
}

这里每个字段的作用是：

  • label：前端显示的专题名，写中文
  • position：专题在当前目录下的排序
  • link.type：必须是 generated-index
  • link.slug：给“全部文章”这套自动分类页用的英文地址
  • description：专题索引页上的简短说明

第三步：把专题下的文章放进去​

专题文章直接放在这个目录下。

例如：

docs/SuperComputer/slurm-scheduler-system/scheduler-system-overview.mdx
docs/SuperComputer/slurm-scheduler-system/slurm-basic-usage.mdx
docs/SuperComputer/slurm-scheduler-system/slurm-advanced-usage.mdx
docs/SuperComputer/slurm-scheduler-system/slurm-common-issues-and-solutions.mdx

普通文章的最小模板可以是：

---
sidebar_position: 1
---

# 文章中文标题

这里写文章导语。

如果是 PDF 预览页，继续复用：

什么时候只写 _category_.json 就够了​

如果这个板块完全依赖文件系统自动生成侧边栏，而且你只关心“全部文章”里的专题页，那么通常只写 _category_.json 就够了。

什么时候还必须改 sidebars.js​

如果这个板块在导航栏里有自己的独立 sidebar，而且这个 sidebar 不是纯文件系统自动展开，而是像下面这样显式组织的：

  • DataStructerSidebar
  • SuperComputerSidebar
  • PythonSidebar

那你不能只创建目录和 _category_.json，还必须同步改 sidebars.js。

否则常见结果会是：

  • “全部文章”里能看到这个专题
  • 但这个板块自己的专栏页里，点击行为不对
  • 或者根本没有你想要的专题入口
  • 或者点击后直接进第一篇文章，而不是专题索引页

第四步：在 sidebars.js 里显式挂上这个专题​

对于有独立 sidebar 的板块，专题应使用：

  • createTopLevelAutogeneratedCategoryWithLink

并放到对应板块的 items 里。

参考模板：

createTopLevelCategoryWithLink({
  label: 'SuperComputer',
  slug: '/SuperComputer',
  description: '超算环境、集群工具与并行计算实践。',
  items: [
    createTopLevelAutogeneratedCategoryWithLink({
      label: 'Slurm调度系统',
      dirName: 'SuperComputer/slurm-scheduler-system',
      slug: '/SuperComputer/slurm-scheduler-system',
      description: '围绕 Slurm 调度系统整理的资料入口。',
    }),
    ...SUPER_COMPUTER_ROOT_DOC_IDS,
  ],
})

这里要特别注意两件事。

1. 专题的 slug 要写成板块路径​

例如：

/SuperComputer/slurm-scheduler-system
/DataStructer/sorting-algorithms

这样这个板块自己的 sidebar 点击专题时，才会进入：

/docs/SuperComputer/slurm-scheduler-system
/docs/DataStructer/sorting-algorithms

这正是你想要的专题索引页地址。

2. 板块根目录的文章顺序要显式维护​

如果像 SuperComputerSidebar 这样从“纯自动生成”改成“显式组织”，就要把板块根目录那些不在专题子目录里的文章顺序一起列出来。

当前仓库里用的方式是：

const SUPER_COMPUTER_ROOT_DOC_IDS = [
  'SuperComputer/mcc24-review',
  'SuperComputer/diy-docker-image',
  // ...
];

然后再在 sidebar 里：

items: [
  createTopLevelAutogeneratedCategoryWithLink(...),
  ...SUPER_COMPUTER_ROOT_DOC_IDS,
]

这样做的目的只有一个：

  • 保持专题之外的文章顺序稳定

第五步：不要再手写专题首页​

一旦 sidebars.js 和 _category_.json 都配好了，专题索引页就应该完全交给 Docusaurus 自动生成。

也就是说，不要再额外创建：

docs/<Section>/<topic-dir>/index.mdx

除非你的目标已经不再是“自动专题索引页”，而是明确想做一篇手写首页。

路由该怎么理解​

以后新增专题时，可以直接按下面的规则理解路由。

1. _category_.json 里的 slug​

这条通常给“全部文章”或自动分类页使用，例如：

/category/slurm-scheduler-system

最终访问路径一般会是：

/docs/category/slurm-scheduler-system

2. sidebars.js 里专题项的 slug​

这条给板块自己的 sidebar 使用，例如：

/SuperComputer/slurm-scheduler-system

最终访问路径一般会是：

/docs/SuperComputer/slurm-scheduler-system

这就是“点超算专栏里的专题索引，先进入专题页”的那条路由。

不要这样做​

以后新增专题目录时，默认不要再犯下面这几类错误。

错误 1：把 _category_.json 写成 link.type: "doc"​

后果：

  • 点击专题时会进某一篇文档
  • 不是自动专题索引页

错误 2：为了做专题首页，手写 index.mdx​

后果：

  • 占用专题路由
  • 把 generated-index 挤掉
  • 点击专题时行为变成“进入手写文档”

错误 3：只创建目录和文章，不改显式 sidebar​

后果：

  • “全部文章”里可能能看到专题
  • 但专栏导航里的专题点击行为不对
  • 或者根本拿不到 /docs/<Section>/<topic-dir> 这条路由

错误 4：目录名、文件名直接写中文​

后果：

  • 路径可读性和稳定性下降
  • 后续手动引用、搜索、迁移都更麻烦

这个仓库以后统一按“英文路径 + 中文显示名”处理。

推荐的最小模板​

_category_.json​

{
  "label": "专题中文名",
  "position": 0,
  "link": {
    "type": "generated-index",
    "slug": "/category/topic-slug",
    "description": "专题简介。"
  }
}

文章模板​

---
sidebar_position: 1
---

# 文章中文标题

这里写导语。

sidebars.js 专题模板​

createTopLevelAutogeneratedCategoryWithLink({
  label: '专题中文名',
  dirName: 'Section/topic-dir',
  slug: '/Section/topic-dir',
  description: '专题简介。',
})

每次创建完之后都要验证​

至少跑一次：

npm run build

然后检查这几件事：

  1. 构建没有 duplicate routes
  2. 构建没有 broken links
  3. 左侧侧边栏点击专题时，先进入专题索引页
  4. 专题索引页会自动列出专题下的文章
  5. 专题下的文章顺序正确
  6. 浏览器链接保持英文路径

以后默认按这条规则执行​

以后在这个仓库里说“新建一个专题目录”，默认就按下面这套理解执行：

  1. 用英文目录名和英文文件名建目录
  2. 用 _category_.json 配 generated-index
  3. 文章只保留必要 front matter
  4. 如果该板块有独立 sidebar，就同步改 sidebars.js
  5. 不再手写 index.mdx
  6. 最后跑 npm run build

这样创建出来的专题目录，点击行为才会稳定，和现在的 排序算法、Slurm调度系统 保持一致。