RFC 文档命名规范

概述

本规范定义了 RFC 文档在本仓库中的标准化命名规则，旨在确保多语言、多章节文档的一致性和可维护性。

核心原则

1. 全局一致性原则

• 跨语言统一：所有语言版本（中文、英文、德文等）使用完全相同的文件名
• 仅内容翻译：翻译工作仅涉及文件内容，文件名保持不变
• 路径对应性：不同语言的相同文件应具有相同的相对路径结构

2. 可读性与可维护性

• 文件名应清晰反映章节内容
• 便于文件系统排序和查找
• 支持自动化工具处理

---

命名规范定义

基础格式

{章节号}-{slug}.md

组成部分：

部分	说明	示例
章节号	章节编号，使用连字符分隔多级编号	1, 3-1, 8-2-1
分隔符	使用单个连字符 -	-
slug	章节标题的 URL 友好形式	introduction, device-authorization
扩展名	始终使用小写 .md	.md

---

详细规则

1. 章节编号格式

一级章节

格式：{数字}-{slug}.md
示例：1-introduction.md
     2-terminology.md
     15-references.md

多级章节

格式：{父级}-{子级}-{slug}.md
示例：3-1-device-authorization.md
     8-2-1-neighbors-and-parents.md
     4-3-2-1-specific-subsection.md

规则：

• 使用连字符 - 连接所有层级的数字
• 最后一个连字符后接 slug
• 不限制层级深度，但建议不超过 4 级

索引文件

格式：index.md
用途：RFC 概览页面，位于每个 RFC 根目录
示例：docs/rfc-9113/index.md
     i18n/de/docusaurus-plugin-content-docs/current/rfc-9113/index.md

2. Slug 规则

基础规则

• 全小写：所有字母必须小写
• 连字符分隔：单词之间使用单个连字符 -
• 仅字母数字：仅包含 a-z、0-9 和 -
• 无特殊字符：禁止使用 _、.、空格、/ 等

生成方法

// 标准 slug 转换流程
const generateSlug = (title) => {
  return title
    .toLowerCase()                    // 转小写
    .replace(/[^\w\s-]/g, '')        // 移除特殊字符
    .replace(/\s+/g, '-')            // 空格转连字符
    .replace(/-+/g, '-')             // 多个连字符合并为一个
    .replace(/^-+|-+$/g, '');        // 移除首尾连字符
};

示例转换

原始标题	Slug
Introduction	introduction
Protocol Overview	protocol-overview
Device Authorization Flow	device-authorization-flow
Security Considerations	security-considerations
IANA Considerations	iana-considerations
Authors' Addresses	authors-addresses
HTTP/2 Frame Format	http2-frame-format
BGP-4 Protocol	bgp-4-protocol

3. 特殊章节命名

附录

格式：appendix-{字母}-{slug}.md
示例：appendix-a-examples.md
     appendix-b-implementation-notes.md
     appendix-c-1-detailed-subsection.md

致谢/作者信息

标准命名：
- authors-addresses.md       (作者地址)
- acknowledgements.md         (致谢)
- acknowledgments.md          (美式拼写，与原文保持一致)

参考文献

标准命名：
- references.md              (所有参考文献)
- normative-references.md    (规范性参考)
- informative-references.md  (信息性参考)

IANA/安全相关

标准命名：
- iana-considerations.md
- security-considerations.md

---

不同 RFC 类型的处理

单文件 RFC

结构：
docs/rfc-XXXX/
  └── index.md

说明：对于内容较少的 RFC，可以使用单文件 index.md

多章节拆分 RFC（推荐）

结构：
docs/rfc-9113/
  ├── index.md                           # 概览
  ├── 1-introduction.md
  ├── 2-protocol-overview.md
  ├── 3-1-connection-preface.md
  ├── 3-2-frame-format.md
  ├── 10-security.md
  └── 11-iana.md

说明：每个章节独立文件，便于维护和翻译

带附录的 RFC

结构：
docs/rfc-4122/
  ├── index.md
  ├── 1-introduction.md
  ├── 4-specification.md
  ├── 7-acknowledgments.md
  ├── appendix-a-uuid-examples.md
  ├── appendix-b-parsing-uuid.md
  └── appendix-c-namespace-ids.md

---

跨语言文件结构

标准目录结构

rfcInfo/
├── docs/                                # 默认语言（英文或中文）
│   └── rfc-9113/
│       ├── index.md
│       ├── 1-introduction.md
│       └── 2-protocol-overview.md
│
└── i18n/
    ├── de/                              # 德语
    │   └── docusaurus-plugin-content-docs/current/
    │       └── rfc-9113/
    │           ├── index.md
    │           ├── 1-introduction.md    # 文件名完全相同
    │           └── 2-protocol-overview.md
    │
    ├── zh/                              # 简体中文
    │   └── docusaurus-plugin-content-docs/current/
    │       └── rfc-9113/
    │           ├── index.md
    │           ├── 1-introduction.md
    │           └── 2-protocol-overview.md
    │
    └── ja/                              # 日语
        └── docusaurus-plugin-content-docs/current/
            └── rfc-9113/
                ├── index.md
                ├── 1-introduction.md
                └── 2-protocol-overview.md

关键要求

✅ 正确做法：

• 所有语言的文件名完全一致
• 仅内容被翻译
• 文件路径结构一致

❌ 错误做法：

• 翻译文件名：1-introduction.md → 1-简介.md
• 改变文件结构
• 使用不同的章节编号

---

命名检查与验证

自动化验证规则

规则列表：
1. 文件名必须全小写
2. 仅允许字符：a-z, 0-9, -, .
3. 必须以 .md 结尾
4. 章节编号与 slug 之间必须有且仅有一个连字符
5. slug 中单词之间使用单个连字符分隔
6. 禁止使用下划线、空格、驼峰命名
7. 跨语言文件名必须完全一致

命名模式正则表达式

# 标准章节文件
^(\d+(-\d+)*)-([a-z0-9]+(-[a-z0-9]+)*)\\.md$

# 附录文件
^appendix-[a-z](-\d+)?-([a-z0-9]+(-[a-z0-9]+)*)\\.md$

# 索引文件
^index\\.md$

# 完整匹配（包含特殊文件）
^(index|(\d+(-\d+)*)-([a-z0-9]+(-[a-z0-9]+)*)|appendix-[a-z](-\d+)?-([a-z0-9]+(-[a-z0-9]+)*)|authors-addresses|acknowledgements?|references|normative-references|informative-references|iana-considerations|security-considerations)\\.md$

---

迁移指南

现有文件的重命名

常见问题修正

当前命名	问题	正确命名
1.Introduction.md	大写+点号	1-introduction.md
2.Protocol_Overview.md	大写+下划线	2-protocol-overview.md
3_1_Device_Auth.md	下划线分隔	3-1-device-auth.md
10.Security.md	点号分隔	10-security.md
Appendix_A.md	大写+下划线	appendix-a.md
Authors_Addresses.md	大写+下划线	authors-addresses.md

批量重命名脚本

见配套的 scripts/rename-files.sh 和 scripts/validate-naming.js

---

工具支持

命名验证脚本

• 位置：scripts/validate-naming.js
• 用途：验证所有文件是否符合命名规范
• 使用：npm run validate:naming

CI/CD 集成

• 位置：.github/workflows/naming-check.yml
• 触发：PR 提交时自动检查
• 阻断：命名不规范时阻止合并

IDE 集成建议

• VSCode 插件：使用文件重命名提示
• 预提交钩子：自动检查命名规范

---

常见问题

Q1: 为什么不使用中文文件名？

A:

1. 兼容性：避免不同操作系统的编码问题
2. 可读性：英文 slug 更易于 URL 路径
3. 维护性：多语言项目需要统一的文件标识

Q2: 章节编号与原文不一致怎么办？

A:

• 优先使用原 RFC 的官方章节编号
• 如果原文无明确编号，按照逻辑顺序编号
• 在 frontmatter 中添加 original_section 字段记录原始编号

Q3: 如何处理超长章节标题？

A:

• 提取核心关键词
• 限制 slug 长度在 50 字符以内
• 示例：8-2-1-neighbors-and-parents-within-dodag-version.md → 8-2-1-neighbors-and-parents.md

Q4: README.md 文件如何命名？

A:

• 如果是 RFC 概览，应命名为 index.md
• 如果是项目说明，可保留 README.md（通常位于仓库根目录）

---

示例对照表

完整 RFC 文件列表示例

docs/rfc-9113/
├── index.md
├── 1-introduction.md
├── 2-protocol-overview.md
├── 3-starting-http2.md
├── 3-1-http2-version-identification.md
├── 3-2-starting-http2-for-http-uris.md
├── 3-3-starting-http2-for-https-uris.md
├── 3-4-starting-http2-with-prior-knowledge.md
├── 4-http-frames.md
├── 4-1-frame-format.md
├── 4-2-frame-size.md
├── 4-3-header-compression-and-decompression.md
├── 5-streams-and-multiplexing.md
├── 5-1-stream-states.md
├── 5-2-flow-control.md
├── 10-security.md
├── 11-iana.md
├── 12-references.md
├── 12-1-normative-references.md
├── 12-2-informative-references.md
├── appendix-a-tls-1-2-cipher-suite-black-list.md
├── acknowledgements.md
└── authors-addresses.md

---

版本历史

版本	日期	变更说明
1.0.0	2026-03-27	初始版本，建立命名规范标准

---

参考资料

• Docusaurus 文档组织最佳实践
• URL Slug 标准
• 文件系统命名惯例

---

维护者: RFC 文档翻译团队
联系方式: 见仓库 CONTRIBUTING.md