文档结构规范

层级定义

1.1 文档层级体系

文档采用四级层级结构，各层级定义如下：

1.1.1 章（Chapter）

定义：左侧导航栏中某个大类下的子菜单项
作用：划分某个领域的具体规范类别
示例：文档规范、代码规范、Git规范（都在"规范"大类下）

1.1.2 节（Section）

定义：章内的具体页面，对应一个独立的 .md 文件
作用：承载章内某个主题的完整内容
示例：文档结构、命名规范、内容规范（都在"文档规范"章下）

1.1.3 条（Article）

定义：页面内的二级标题（##）
作用：组织页面内的主要内容块
示例：第一条层级定义、第二条组织原则

1.1.4 款（Clause）

定义：页面内的三级标题（###）
作用：条内的具体规则说明
示例：1.1 文档层级体系、1.2 标题编号规则

组织原则

2.1 内容组织

2.1.1 单一职责

每个文档页面应聚焦于单一主题，避免内容过于分散。

2.1.2 逻辑递进

内容应按照从总到分、从简到繁的逻辑顺序组织。

2.1.3 适度拆分

当单个页面内容超过 500 行时，应考虑拆分为多个子页面。

2.2 目录结构

2.2.1 标准目录结构

docs/
├── zh/                     # 中文文档
│   ├── standards/         # 规范章
│   │   ├── index.md      # 章首页
│   │   ├── documentation/ # 文档规范子章
│   │   │   ├── index.md  # 子章首页
│   │   │   ├── structure.md  # 具体规范页
│   │   │   └── naming.md     # 具体规范页
│   │   └── coding/        # 代码规范子章
│   └── projects/          # 项目章
└── en/                    # 英文文档

2.2.2 文件组织规则

每个章必须有 index.md 作为首页
相关内容组织在同一目录下
目录层级不超过 3 层

标题规范

3.1 标题层级使用

3.1.1 Markdown 标题对应关系

markdown

# 节标题（Section） - 页面标题
## 第N条 条标题（Article） - 主要内容块
### N.N 款标题（Clause） - 具体规则
#### N.N.N 项标题（Item） - 详细说明

3.1.2 标题编号规则

条：使用"第N条"格式，如"第一条"、"第二条"
款：使用"N.N"格式，如"1.1"、"2.1"
项：使用"N.N.N"格式，如"1.1.1"、"2.3.1"

3.2 标题书写要求

3.2.1 简明扼要

标题应准确概括内容，避免冗长。

3.2.2 平行结构

同级标题应保持语法结构一致。

3.2.3 避免标点

标题末尾不使用标点符号。

导航配置

4.1 侧边栏配置

4.1.1 配置位置

在 .vitepress/config.mjs 中配置侧边栏导航。

4.1.2 配置示例

javascript

sidebar: {
  '/zh/standards/': [
    {
      text: '规范',
      items: [
        { text: '概述', link: '/zh/standards/' },
        { text: '文档规范', link: '/zh/standards/documentation/' }
      ]
    }
  ]
}

文档结构规范

层级定义

1.1 文档层级体系

1.1.1 章（Chapter）

1.1.2 节（Section）

1.1.3 条（Article）

1.1.4 款（Clause）

组织原则

2.1 内容组织

2.1.1 单一职责

2.1.2 逻辑递进

2.1.3 适度拆分

2.2 目录结构

2.2.1 标准目录结构

2.2.2 文件组织规则

标题规范

3.1 标题层级使用

3.1.1 Markdown 标题对应关系

3.1.2 标题编号规则

3.2 标题书写要求

3.2.1 简明扼要

3.2.2 平行结构

3.2.3 避免标点

导航配置

4.1 侧边栏配置

4.1.1 配置位置

4.1.2 配置示例

4.2 导航层级限制

4.2.1 最大层级

4.2.2 折叠控制

文档结构规范 ​

层级定义 ​

1.1 文档层级体系 ​

1.1.1 章（Chapter） ​

1.1.2 节（Section） ​

1.1.3 条（Article） ​

1.1.4 款（Clause） ​

组织原则 ​

2.1 内容组织 ​

2.1.1 单一职责 ​

2.1.2 逻辑递进 ​

2.1.3 适度拆分 ​

2.2 目录结构 ​

2.2.1 标准目录结构 ​

2.2.2 文件组织规则 ​

标题规范 ​

3.1 标题层级使用 ​

3.1.1 Markdown 标题对应关系 ​

3.1.2 标题编号规则 ​

3.2 标题书写要求 ​

3.2.1 简明扼要 ​

3.2.2 平行结构 ​

3.2.3 避免标点 ​

导航配置 ​

4.1 侧边栏配置 ​

4.1.1 配置位置 ​

4.1.2 配置示例 ​

4.2 导航层级限制 ​

4.2.1 最大层级 ​

4.2.2 折叠控制 ​

文档结构规范

层级定义

1.1 文档层级体系

1.1.1 章（Chapter）

1.1.2 节（Section）

1.1.3 条（Article）

1.1.4 款（Clause）

组织原则

2.1 内容组织

2.1.1 单一职责

2.1.2 逻辑递进

2.1.3 适度拆分

2.2 目录结构

2.2.1 标准目录结构

2.2.2 文件组织规则

标题规范

3.1 标题层级使用

3.1.1 Markdown 标题对应关系

3.1.2 标题编号规则

3.2 标题书写要求

3.2.1 简明扼要

3.2.2 平行结构

3.2.3 避免标点

导航配置

4.1 侧边栏配置

4.1.1 配置位置

4.1.2 配置示例

4.2 导航层级限制

4.2.1 最大层级

4.2.2 折叠控制