如何规范写出 README 模板？

README 标准是由 RichardLitt 发起，十多名开发者共同贡献完成的，在 GitHub 上有 1230+ Star：standard-readme

标准 README 实例：

• standard-readme/tree/main/example-readmes
• 奖励：实例

本文模板获取地址： README-Template

README

文件是人们通常最先看到的第一个东西。它应该告诉人们为什么要使用、如何安装、以及如何使用你的代码。

README

文件标准化能够使得创建和维护

README

文件更加简单。毕竟，要写好一个文档不是那么容易的。

1. Sections

Title

Status: Required.

Requirements:

• 标题必须与 repository、folder 和 package manager names 匹配 - 或者它可能有另一个相关的标题，repository、folder 和 package manager title 旁边以斜体和括号显示。例如：

# Standard Readme Style _(standard-readme)_

If any of the folder, repository, or package manager names do not match, there must be a note in the

Long Description

explaining why.

Suggestions:

• Should be self-evident.

Banner

Status: Optional.

Requirements:

• Must not have its own title.
• Must link to local image in current repository.
• Must appear directly after the title.

Badges

Status: Optional.

Requirements:

• Must not have its own title.
• Must be newline delimited.

Suggestions:

• Use http://shields.io or a similar service to create and host the images. Add the Standard Readme badge.

Short Description

Status: Required.

Requirements:

• Must not have its own title.
• Must be less than 120 characters.
• Must not start with >
• Must be on its own line.
• Must match the description in the packager manager’s description field.
• Must match GitHub’s description (if on GitHub).

Suggestions:

• Use gh-description to set and get GitHub description.
• Use npm show . description to show the description from a local npm package.

Long Description

Status: Optional.

Requirements:

• Must not have its own title.
• If any of the folder, repository, or package manager names do not match, there must be a note here as to why. See Title section.

Suggestions:

• If too long, consider moving to the Background section.
• Cover the main reasons for building the repository.
• "This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module’s routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections.这应该广泛地描述你的模块，通常只有几个段落;关于模块的例程或方法、冗长的代码示例或其他深入材料的更多细节将在后续章节中给出。

Ideally, someone who’s slightly familiar with your module should be able to refresh their memory without hitting “page down”. As your reader continues through the document, they should receive a progressively greater amount of knowledge."理想情况下，稍微熟悉您的模块的人应该能够刷新他们的内存，而不需要点击“下一页”。当你的读者继续阅读文档时，他们会逐渐获得更多的知识。

Table of Contents

Status: Required; optional for READMEs shorter than 100 lines.

Requirements:

• Must link to all Markdown sections in the file. 必须链接到文件中的所有 Markdown 部分。
• Must start with the next section; do not include the title or Table of Contents headings. 必须从下一节开始;不要包括标题或目录标题。
• Must be at least one-depth: must capture all ## headings.

Suggestions:

• May capture third and fourth depth headings. If it is a long ToC, these are optional.

Security

Status: Optional.

Requirements:

• May go here if it is important to highlight security concerns. Otherwise, it should be in Extra Sections.

Background

Status: Optional.

Requirements:

• Cover motivation.
• Cover abstract dependencies.
• Cover intellectual provenance: A See Also section is also fitting.

Install

Status: Required by default, optional for documentation repositories.

Requirements:

• Code block illustrating how to install.

Subsections:

• Dependencies. Required if there are unusual dependencies or dependencies that must be manually installed. 如果存在不寻常的依赖项或必须手动安装的依赖项，则必需。

Suggestions:

• Link to prerequisite sites for programming language: npmjs, godocs, etc.
• Include any system-specific information needed for installation. 包括安装所需的任何系统特定信息。
• An Updating section would be useful for most packages, if there are multiple versions which the user may interface with. 如果用户可能接触到多个版本的包，则 update 部分对于大多数包都很有用。

Usage

Status: Required by default, optional for documentation repositories.

Requirements:

• Code block illustrating common usage. 说明常用用法的代码块。
• If CLI compatible, code block indicating common usage. 如果兼容CLI，表示常用的代码块。
• If importable, code block indicating both import functionality and usage. 如果可导入，则表示导入功能和使用情况的代码块。

Subsections:

• CLI. Required if CLI functionality exists.

Suggestions:

• Cover basic choices that may affect usage: for instance, if JavaScript, cover promises/callbacks, ES6 here. 涵盖可能影响使用的基本选择：例如，如果是 JavaScript，请在​​此处涵盖 promises/callbacks、ES6。
• If relevant, point to a runnable file for the usage code. 如果相关，指向使用代码的可运行文件。

Extra Sections

Status: Optional.

Requirements:

• None.

Suggestions:

• This should not be called Extra Sections. This is a space for 0 or more sections to be included, each of which must have their own titles.
• This should contain any other sections that are relevant, placed after Usage and before API.
• Specifically, the Security section should be here if it wasn’t important enough to be placed above.

API

Status: Optional.

Requirements:

• Describe exported functions and objects. 描述导出的函数和对象。

Suggestions:

• Describe signatures, return types, callbacks, and events. 描述签名、返回类型、回调和事件。
• Cover types covered where not obvious. 覆盖不明显的覆盖类型。
• Describe caveats. 描述说明。
• If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present. 如果使用外部API生成器(如go-doc, js-doc等)，则指向外部“API”。md的文件。如果存在，这可以是节中唯一的项。

Thanks

Status: Optional.

Requirements:

• Must be called Thanks, Credits or Acknowledgements.

Suggestions:

• State anyone or anything that significantly helped with the development of your project.
• State public contact hyper-links if applicable.

Contributing

Status: Required.

Requirements:

• State where users can ask questions.
• State whether PRs are accepted.
• List any requirements for contributing; for instance, having a sign-off on commits.

Suggestions:

• Link to a CONTRIBUTING file – if there is one.
• Be as friendly as possible.
• Link to the GitHub issues.
• Link to a Code of Conduct. A CoC is often in the Contributing section or document, or set elsewhere for an entire organization, so it may not be necessary to include the entire file in each repository. However, it is highly recommended to always link to the code, wherever it lives.
• A subsection for listing contributors is also welcome here.

License

Status: Required.

Requirements:

• State license full name or identifier, as listed on the SPDX license list. For unlicensed repositories, add UNLICENSED. For more details, add SEE LICENSE IN <filename> and link to the license file. (These requirements were adapted from npm).
• State license owner.
• Must be last section.

Suggestions:

• Link to longer License file in local repository.

Definitions

These definitions are provided to clarify any terms used above.

• Documentation repositories: Repositories without any functional code. For instance, RichardLitt/knowledge.

2. Chicken-Swarm-Optimization

源地址： https://github.com/decipher07/Chicken-Swarm-Optimization

2. pyswarm

源地址： https://github.com/tisimst/pyswarm

https://pythonhosted.org/pyswarm/

3. minimal-readme.md

源地址： standard-readme/blob/main/example-readmes/minimal-readme.md

4. 模板四

4. 王者版

# Title[![license](https://camo.githubusercontent.com/4738d430387c93da0d49ef0428a7c7ddae18e81eaff99a014996d4f6b30fd3ef/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f3a757365722f3a7265706f2e737667)](https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/LICENSE)[![standard-readme compliant](https://camo.githubusercontent.com/f116695412df39ab3c98d8291befdb93af123f56aecc79fff4b20c410a5b54c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f726561646d652532307374796c652d7374616e646172642d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/RichardLitt/standard-readme)

This is an example file with maximal choices selected.

This is a long description.

## Table of Contents

- [Install](#Install)
- [Configuration](#Configuration)（可选）
- [Usage](#Usage)
- [API](#API)
- [Contributing](#Contributing)
- [License](#License)## Install

Using [npm](https://www.npmjs.org/), just run the following command:

\```npminstall box-intersect
\```

This module works in any reasonable CommonJS environment, such as browsersify, iojs or node.js.

## Configuration## API## Contributing## License

5. 终极版

# Title[![license](https://camo.githubusercontent.com/4738d430387c93da0d49ef0428a7c7ddae18e81eaff99a014996d4f6b30fd3ef/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f3a757365722f3a7265706f2e737667)](https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/LICENSE)[![standard-readme compliant](https://camo.githubusercontent.com/f116695412df39ab3c98d8291befdb93af123f56aecc79fff4b20c410a5b54c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f726561646d652532307374796c652d7374616e646172642d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/RichardLitt/standard-readme)## About The Project

This is an example file with maximal choices selected.

This is a long description.

### Built With

Built Using Languages and Libraries Listed Below 
* [Python](https://docs.python.org/3/)
* [Java](https://docs.oracle.com/en/java/)
* [numpy](https://numpy.org/devdocs/)
* [sklearn](https://scikit-learn.org/stable/)

Or in tabular form

| environment | version   || ----------- | --------- || Python      |3.7 ~ 3.8|| Java        ||| numpy       ||| sklearn     ||## Table of Contents

- [Getting Started](#Getting Started)

  - [Install](#Install)

  - [Configuration](#Configuration)**（可选）**

  - [Usage](#Usage)

- [API](#API)

- [Contributing](#Contributing)

- [License](#License)## Getting Started### Install

Using [npm](https://www.npmjs.org/), just run the following command:

\```npminstall box-intersect
\```

This module works in any reasonable CommonJS environment, such as browsersify, iojs or node.js.

### Configuration### Usage## API## Contributing## License

References

[1] 编写规范的readme文件

[2] 我们应该如何书写README及文档

[3] 如何写好Github中的readme？

[4] README.md文件的必要性

[5] 如何为开发项目编写规范的README文件（windows），此文详解