标准的README

原创已于 2024-01-24 17:03:51 修改 · 1.1k 阅读

17 ·

CC 4.0 BY-SA版权

文章标签：

#README #GitHub

于 2024-01-24 16:37:10 首次发布

Github 专栏收录该内容

8 篇文章

订阅专栏

GitHub 中标准的 README.md 写法。内容整理自：RichardLitt/standard-readme: A standard style for README files，部分内容没有实践，仍在修改中。

标题

标题必须与仓库、文件夹和包管理器名称相匹配——或者用斜体和括号表示的相关副标题。例如:

Standard Readme Style (standard-readme)

如果任何文件夹、仓库或包管理器名称不匹配，必须在“长描述”中附注说明原因。

![bannar](url)

横幅。不能有自己的标题；必须链接到当前存储库中的本地映像；必须直接出现在标题后面

![badge](url)

徽章。不能有自己的标题，必须用换行符分隔；使用 http://shields.io 或类似的服务来创建和托管图像；添加 Standard Readme badge 徽章.

简短描述

要求:

不能有自己的标题

必须少于120个字符

不能以 > 开始

独立成段

必须符合包管理器的描述字段

必须符合 GitHub 的描述(如果在 GitHub 上)

建议：

使用gh-description 描述设置并获取 GitHub 描述
使用npm show . description 来展示本地的描述 npm 包

详细描述（可选）

要求:

不能有自己的标题
如果任何文件夹、存储库或包管理器名称不匹配，则必须在这里说明原因。看标题部分

建议:

如果太长，考虑移动到背景部分。
包含构建储存库的主要原因。
“这应该大致地描述你的模块，通常只有几个段落; 模块的例程或方法的更多细节，冗长的代码示例，或其他深入的材料应该在随后的章节中给出。理想情况下，对您的模块稍微熟悉的人应该能够刷新他们的记忆，而不必按下“页面向下”键。当你的读者继续阅读文档时，他们应该会接收到越来越多的知识。”

状态：必需的; 对于小于100行的 README 可选。

要求：

必须链接到文件中的所有 Markdown 部分
必须从下一节开始，不要包括标题或目录标题
必须至少有一个深度: 必须捕获所有 ## 标题

建议：可以捕获第三个和第四个深度标题。如果是长目录，这些是可选的.

安全
背景
安装
用法
API
额外说明
维护者
致谢
如何贡献
许可证

安全

状态：可选
要求：如果需要强调安全问题，可以在这里，否则应该在额外部分

背景

状态：可选

要求：
包含动机
包含抽象依赖关系.
包含知识来源: 可参见也很合适.

安装

状态: 默认情况下是必需的，文档存储库是可选的.

要求:
说明如何安装的代码块

子段落:
如果有不寻常的依赖项或依赖项，必须手动安装
建议: -链接到编程语言的必备站点: npmjs, godocs,等等.

包括安装所需的任何系统特定信息.
一个更新部分对大多数软件包都很有用, 如果用户可以使用多个版本.

例如：
这个项目使用 node 和 npm。请确保你本地安装了它们。

$ npm install --global standard-readme-spec

用法

状态: 默认情况下是必需的，文档存储库是可选的.

要求:
说明常用用法的代码块.
如果 CLI 兼容，则代码块指示通用用法.
如果可导入，则指示导入功能和用法的代码块.
建议:

CLI. 如果 CLI 功能存在，则需要.

建议:
涵盖可能影响使用的基本选项: 例如，如果是 JavaScript，则涵盖 promises / callbacks，此处为 ES6
如果相关，指向一个可运行的文件以获取使用代码

API

状态: 可选

要求:
描述暴露出的功能和对象.

建议:
描述签名、返回类型、回调和事件.
指明不容易理解的类型.
描述注意事项.
如果使用外部 API 生成器(比如 go-doc、 js-doc 等等) ，请指向外部 API.md 文件. 这可能是该节中的唯一项，如果存在的话

额外部分

状态: 可选.

要求:没有.

建议:
这不应该被称为额外部分. 这是一个包含0个或更多部分的空间，每个部分都必须有自己的标题
这应该包含任何其他相关的部分,放在用法之后, API 之前.
具体来说，就是, 安全部分如果没有重要到可以放在上面的话，这个部分应该在这里.

维护者

状态: 可选.

要求:

一定要叫维护者
列出存储库的维护人员，以及与他们联系的一种方式(例如 GitHub 链接或电子邮件).

建议:

这应该是一个负责项目方向的人员名单。这不应该是拥有访问权限的每个人，比如整个组织，应该被展示的人是负责存储库的指导和维护的人
列出过去的维护人员对于属性和分类都有好处.

致谢

状态: 可选.

要求:

一定要叫做致谢或者感谢.

建议:

说明对项目的开发有重要帮助的任何人或任何事情
标明公共链接，如果适用的话

如何贡献

状态: 必需.

要求:

说明用户可以提问的地方.
说明是否接受 PR .
列出贡献的所有要求; 例如，在提交时有一个签名.

建议:

链接到如何贡献文件–如果有的话
尽可能友好
链接到 GitHub issues 区域.
链接到行为守则. 如何贡献规范通常位于贡献部分或文档中,或者位于整个组织的其他位置，因此可能不需要在每个存储库中包含整个文件。但是，强烈建议始终链接到规范位置，无论它位于何处.
这里也欢迎列出贡献者的子段落.

许可证

状态: 必须

要求:

声明许可证全名或标识符, 参考SPDX 许可证列表上的. 对于未授权的存储库, 添加 UNLICENSED. 更多详情，请参见 SEE LICENSE IN <filename> 并链接到许可文件. (这些要求是从 npm继承过来的).
声明许可证持有人.
一定是最后一部分.

建议:

链接到本地存储库中较长的许可证文件