RFC 文档命名规范

概述

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

核心原则

1. 全局一致性原则

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

2. 可读性与可维护性

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

详细规则

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

跨语言文件结构

标准目录结构

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.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

常见问题

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（通常位于仓库根目录）

版本历史

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

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