standard-readme 规范详解：为开源项目编写标准、可维护、易检索的 README-育师

文档
开发工具

【免费下载链接】standard-readme

A standard style for README files

项目地址：https://gitcode.com/gh_mirrors/st/standard-readme

本文围绕开源仓库 standard-readme 的中文说明文档展开，系统讲解"标准 Readme"的定位、诞生背景、完整的段落规范（含每个段落的状态、要求与建议）、本地安装与 CLI 用法、合规徽章的使用方式以及极简/全量两类示例 README。读完本文，你将掌握一套可直接套用的 README 写作框架：既能保证内容完整、段落顺序统一，又能让用户、搜索引擎与自动化工具（linter、生成器）快速理解与解析你的项目文档。

什么是 standard-readme

README 文件是大多数人接触代码时看到的第一个东西，它应当回答三个问题：为什么要使用这个模块、如何安装它、以及如何使用它。standard-readme 正是为了把这份"门面文档"标准化而生的仓库——它定义了一种 README 样式标准，让创建和维护 README 变得更容易，因为"写好一份文档需要付出不少努力"。

本仓库（见 README.zh-CN.md）包含五部分内容：

一份标准 README 应该长什么样的规范，即 spec.md（另有中文译本 spec.zh-CN.md）；
一个用于检查 README 语法错误的**提示工具（linter）**的链接（该项目仍处于进行中状态）；
一个用于快速创建标准 README 的生成器（generator-standard-readme）；
一个指向该规范的徽章，供合规项目引用；
一批标准 README 的实例，位于 example-readmes/ 目录——你正在阅读的这份 README 本身就是完全合规的范例。

需要特别强调的是：标准 Readme 是为开源组件设计的。尽管它在历史上源于 Node 与 npm 项目，但同样适用于其他编程语言和包管理器。也就是说，这套规范并不绑定 JavaScript 生态，任何语言的库都可以采用。

背景：为什么 README 需要标准化

标准 Readme 的念头最初由 @maxogden 在 feross/standard 项目的一个 Issue 中提出：一个"标准化 README 的工具"是否有用。随后大量讨论汇集在 zcei 的 standard-readme 仓库中；而在维护 IPFS 系列仓库时，作者需要一种方式在组织内统一 README 风格，这份规范便由此诞生。

规范背后有一个核心理念，引用自 Perl 社区（Ken Williams, Perl Hackers）：

如果你的文档是完整的，那么使用你代码的人就不用再去看代码了。这非常重要。它使得你可以分离接口文档与具体实现，意味着你可以修改实现代码而保持接口与文档不变。
请记住：是文档而非代码，定义了一个模块的功能。

写 README 本就费力，持续维护更难。把这一过程"外包"给标准——让写作更容易、编辑更容易、判断一次改动是否符合规范更清晰——你就能少操心初始文档是否合格，把更多时间花在写代码和用代码上。标准化还带来了生态层面的好处：

用户花更少的时间搜索他们需要的信息（段落位置固定，一看便知）；
工具可以从描述中搜集信息、自动运行示例代码、检查授权协议等；
README 的内容与结构可被搜索引擎、代码托管平台与自动化脚本稳定解析。

基于此，仓库确立了五个目标：一份定义良好的规范（持续迭代，欢迎通过 Issue 讨论变更）；一份完全合规的示例 README（本文件，且 example-readmes 文件夹中有更多）；一个语法提示器；一个生成器；一个合规徽章。

规范核心：合规 README 的总则

规范的权威定义在 spec.md，一个合规的 README 必须满足以下总则：

文件名：必须叫README（大写），扩展名视格式而定（Markdown 用.md、Org Mode 用.org、HTML 用.html等）；
国际化命名：若项目支持 i18n，文件名须带 BCP 47 语言标签，如README.de.md（de为语言标记，优先使用非区域子标记）；若项目只有一个 README 且非英语，则该文件可以直接使用其他语言而无需标注；当存在多个语言版本时，README.md保留给英语版本；
有效性：必须是所选格式（Markdown、Org Mode、HTML 等）下的合法文件；
段落顺序：段落必须按规范给出的顺序出现，可选段落可以省略；
段落标题：必须使用规范列出的标题，除非另有说明；若 README 使用其他语言，标题需翻译成对应语言；
链接：不得包含失效链接；
代码示例：如有代码示例，应遵循项目其余部分相同的 lint 规则。

在这些总则之下，规范定义了 16 个标准段落，状态分为"必须"与"可选"两类。下面逐一展开每个段落的要求与建议。

标题（必须）

标题必须与仓库名、文件夹名和包管理器名称一致；若不一致，则允许在括号中以斜体附上相关标题，例如：

# Standard Readme Style _(standard-readme)_

如果文件夹、仓库或包管理器名称有任何不匹配，必须在"长描述"中附注说明原因。
建议：标题应当自明（self-evident），让人一眼看清项目是什么。

横幅（可选）

不能有自己的标题；
必须链接到当前仓库中的本地图片；
必须直接出现在标题之后。

横幅是 README 顶部的视觉入口，规范刻意要求"本地图片"，避免依赖外部资源。仓库内的横幅示例可参考 example-readmes/assets/text_wordmark_dark.png，其在 maximal-readme.md 中紧跟在标题之后使用。

徽章（可选）

不能有自己的标题；
必须用换行符分隔（每行一个徽章，不要挤在一行）。

建议方面：可以使用 Shields.io 或类似服务创建和托管徽章图片；对于静态徽章，考虑使用本地托管的图片，以避免外部请求带来的追踪问题和多余资源消耗；并建议加上"Standard Readme 合规"徽章。本仓库自身的徽章实践可参考 README.md 顶部，以及 maximal-readme.md 中并排展示的多个徽章（GitHub 创建时间、贡献者数、许可证、合规徽章）。

简短描述（必须）

不能有自己的标题；
必须少于 120 个字符；
不能以>开头（即不能是引用块）；
必须独占一行；
必须与包管理器description字段一致；
如果在 GitHub 上，还必须与 GitHub 仓库描述一致。

这一段的工程意义在于"单一事实来源"：README 首行描述、包管理器的 description 字段、GitHub 描述三者保持一致，搜索引擎和平台才能索引到同一段项目简介。本仓库的 package.json（见 package.json）中description: "A standard style for README files"与 README 首行描述完全一致，正是该要求的实例。建议借助gh-description这类工具同步 GitHub 描述，或用npm show . description查看本地 npm 包的 description。

长描述（可选）

不能有自己的标题；
如果文件夹、仓库或包管理器名称不匹配，必须在这里说明原因（对应"标题"段落的要求）。

建议：如果太长，考虑把内容移到"背景"段落；应当覆盖构建该仓库的主要原因。规范引用了 perlmodstyle 作者 Kirrily "Skud" Robert 的经典建议：长描述应"大致描述你的模块，通常只需几个段落"；更细节的例程或方法、冗长的代码示例和深入内容应放到后续段落。"理想情况下，对模块稍有了解的读者不需要按 Page Down 就能唤起记忆；随着读者继续阅读，他们会获得越来越多的知识。"——这正是 README"自顶向下、由浅入深"的信息架构原则。

目录（必须；不足 100 行的 README 可选）

必须链接到文件中的所有段落；
必须从下一个段落开始，不要包含标题本身和"目录"这个标题；
必须至少有一层深度：必须捕获所有二级标题（Markdown 的##、Org Mode 的**、HTML 的<h2>等）。

建议：可以额外捕获第三、第四级标题；对于很长的目录，这些更深层条目是可选的。目录把 README 变成可快速跳转的导航文档，这是它与"文档而非代码定义模块"理念的直接呼应。

安全（可选）

如果安全问题足够重要、需要突出强调，可以放在这个位置；否则应放进"额外部分"。

背景（可选）

必须覆盖动机（为什么做这个项目）；
必须覆盖抽象依赖（项目依赖的上层概念/生态，而非具体依赖列表）；
必须覆盖知识来源（intellectual provenance），此时设置一个"参见（See Also）"小节也很合适。

安装（默认必须，纯文档仓库可选）

必须包含一个说明如何安装的代码块；
子段落Dependencies：如果存在不寻常的依赖、或需要手动安装的依赖，则该子段落为必须。

建议：可以链接到对应编程语言的必备站点（如 npmjs、godocs）；包含安装所需的系统特定信息；对存在多个版本的包，增加一个Updating（更新）段落会很有用。

用法（默认必须，纯文档仓库可选）

必须包含一个展示常见用法的代码块；
如果支持 CLI，必须给出指示常见用法的代码块；
如果可被导入（importable），必须同时给出导入方式与用法的代码块；
子段落CLI：只要存在 CLI 功能，该子段落就是必须的。

建议：覆盖可能影响使用方式的基本选择——例如 JavaScript 项目要说明 promise/callback、ES6 等用法差异；如果相关，指向一份可运行的用法示例文件。Usage 与 Install 一起构成了 README 的"动手"部分，让用户不读源码就能跑起来。

额外部分（可选）

该位置用于容纳 0 个或多个与项目相关的其他段落，每个段落都必须有自己的标题（不要真的把这一节命名为"额外部分"）；
位置在"用法"之后、"API"之前；
如果"安全"内容不够重要、未放在上方，则应放到这里。

API（可选）

必须描述导出的函数和对象。

建议：描述签名、返回类型、回调和事件；标明不明显（non-obvious）的类型；描述注意事项；如果使用外部 API 生成器（如 go-doc、js-doc 等），可以在此指向一份外部的API.md文件——这种情况下该文件可以是这一节的全部内容。

维护者（可选）

必须命名为Maintainer或Maintainers；
必须列出仓库维护者，并附上至少一种联系方式（如 GitHub 链接或邮箱）。

建议：这应当是一份小名单——真正负责项目方向、应该被 ping 的人，而不是所有拥有访问权限的人（例如整个组织）。列出前任维护者也是一种好的署名与礼貌。

致谢（可选）

必须命名为Thanks、Credits或Acknowledgements；
建议说明对项目开发有重要帮助的人或事，并给出适用的公开联系链接。

如何贡献（必须）

必须说明用户可以在哪里提问；
必须说明是否接受 Pull Request；
必须列出贡献的任何要求（例如提交需要 sign-off）。

建议：链接到 CONTRIBUTING 文件（如果有）；措辞尽量友好；链接到 GitHub issues；链接到行为守则（Code of Conduct）——CoC 常位于贡献段落/文档或组织级位置，不一定在每个仓库重复全文，但强烈建议始终链接到其所在位置；在此处设置一个列出贡献者的子段落也是受欢迎的。

许可证（必须）

必须声明许可证全名或标识符，以 SPDX 许可证列表为准；未授权仓库写UNLICENSED；如需更多细节，写SEE LICENSE IN <filename>并链接到许可证文件（该要求沿袭自 npm 的 package.json 规范）；
必须声明许可证持有人；
必须是最后一个段落。

建议：链接到仓库内更完整的许可证文件。本仓库以 MIT 协议开源，版权归 Richard Littauer，完整文本见 LICENSE，其 license 字段也在 package.json 中声明为MIT——规范、README 与包元数据三者保持一致。

定义：文档存储库

规范中出现的术语"文档存储库（documentation repositories）"指不包含任何功能代码的仓库。这类仓库（例如个人知识库）没有可安装、可运行的功能，因此 Install 与 Usage 段落对它们从"默认必须"降级为"可选"。

安装与使用：把规范打印到终端

规范文档本身就是一份可"运行"的文档包。根据 README.zh-CN.md，本地安装方式如下（项目基于 Node 与 npm，请先确保本地已安装二者）：

$ npm install --global standard-readme-spec

安装后即可在终端打印出 spec.md 的完整内容：

$ standard-readme # Prints out the standard-readme spec

需要说明的是：中文版文档中写作standard-readme-spec，而英文版 README.md 与仓库的实际可执行命令名均为standard-readme——从 package.json 的bin字段可以看到映射关系："standard-readme": "cat.js"，即全局安装后提供的命令是standard-readme。其实现非常轻量，cat.js 的核心逻辑只有两行：用 Node 内置的fs.readFileSync读取与脚本同目录的spec.md，再console.log输出到终端。整个安装使用流程本质上是"把规范文档以 npm 包形式分发，供随时查阅"。

另外，遵循规范本身不需要安装任何东西——规范是一份写作指南，不是运行时依赖。npm 包只是方便你随时把规范打出来对照检查。

生成器：快速搭出 README 框架

如果你不想从零开始排版，可以使用配套的生成器generator-standard-readme快速搭建新的 README 框架。该生成器包提供一个全局可执行文件，命令别名同样是standard-readme，用法请以该生成器包自身的说明为准。生成器 + 规范 + 提示器构成了完整的"创建—校验—维护"工具链：生成器负责脚手架，规范负责定义正确形态，提示器（仍在开发中）负责事后检查语法错误。

徽章：让合规被一眼看见

如果你的项目遵循 Standard-Readme 规范（并且托管在 GitHub 上），非常建议把合规徽章加入 README 顶部——它让读者一眼看到"这份 README 是标准化的"，让更多人访问并采纳该规范。加入徽章并非强制的。

徽章本体使用 Shields.io（一个广受欢迎的、为项目与文档生成可定制徽章的服务）渲染。在 Markdown 中加入徽章的代码如下：

[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)

实践中推荐把徽章放在 README靠近顶部的位置，让重要信息立刻可见；同时不要堆砌过多徽章，过多的徽章会让 README 显得杂乱、降低可读性。徽章在排版上也必须遵守规范：不能有自己的标题，并且每个徽章要用换行符分隔。

示例 README：从极简到全量

想看规范如何落地，可以直接阅读 example-readmes/ 目录下的两份示例：

minimal-readme.md：采用默认最小选项，仅包含规范要求的骨架——标题、简短描述、Install（含代码块）、Usage（含代码块）、Contributing（声明"PRs accepted"）、License（MIT © Richard McRichface）。它演示了"只有必须段落"时 README 应有的样子，也是不足 100 行时可省略目录的依据所在。
maximal-readme.md：采用全量选项，几乎覆盖每个可选段落——标题后紧跟本地横幅图（text_wordmark_dark.png）、四个徽章、简短描述 + 长描述、完整目录（Security/Background/Install/Usage/API/Contributing/License）、Security、Background、Install、Usage、API、更多可选段落、Contributing（并指出编辑 README 需符合 standard-readme 规范）、License。它是理解"每个段落要求与建议"的活教材。

此外，本仓库的 README.md 与 README.zh-CN.md 本身就是完全合规的示例——标题、简短描述、目录、背景、安装、使用、徽章、示例、相关仓库、维护者、贡献、许可证一应俱全，可以逐段对照 spec 学习。

维护、贡献与许可证

维护者：@RichardLitt。
如何贡献：欢迎通过提交 Issue 或 Pull Request 参与；标准 Readme 遵循 Contributor Covenant 1.3.0 行为规范。
许可证：本项目以 MIT 协议发布，版权归 Richard Littauer。

总而言之，standard-readme 提供了一套"有规范、有工具、有范例"的完整方案：以 spec.md 定义 README 的唯一正确骨架，以 example-readmes/ 提供从极简到全量的参照，以 npm 包（standard-readme命令，实现见 cat.js）让规范随手可查，再以徽章形成生态内的可视化认同。无论你的项目使用哪种语言和包管理器，都可以把这份规范直接引入，让 README 从"随手写的说明"升级为"用户、搜索引擎与工具都能稳定依赖的文档接口"。