如何规范写出 README 模板？

article/2025/9/23 13:19:28

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)## InstallUsing [npm](https://www.npmjs.org/), just run the following command:\```
npm install 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 ProjectThis is an example file with maximal choices selected.This is a long description.### Built WithBuilt 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### InstallUsing [npm](https://www.npmjs.org/), just run the following command:\```
npm install 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），此文详解


http://chatgpt.dhexx.cn/article/OjWXUTxp.shtml

相关文章

GitHub README-Template.md - README.md 模板

GitHub README-Template.md - README.md 模板

GitHub README-Template.md - README.md 模板 A template to make good README.md. https://gist.github.com/PurpleBooth/109311bb0361f32d87a2 # Project TitleOne Paragraph of project description goes here## Getting StartedThese instructions will get you a copy o…
阅读更多...
怎么写一个超棒的 README 文档

怎么写一个超棒的 README 文档

点击上方 Java后端&#xff0c;选择 设为星标 优质文章&#xff0c;及时送达 大数据文摘出品 来源&#xff1a;medium 编译&#xff1a;青柠 如果你很着急、只是想要模板&#xff0c;可以直接跳到底部&#xff08;但这样一点不酷&#xff09;&#xff0c;准备酷的人&#xff0c…
阅读更多...
【工具推荐】最简单方法创建 README

【工具推荐】最简单方法创建 README

CSDN话题挑战赛第1期 活动详情地址&#xff1a;https://marketing.csdn.net/p/bb5081d88a77db8d6ef45bb7b6ef3d7f 参赛话题&#xff1a;程序员常用小工具推荐 话题描述&#xff1a;俗话说&#xff0c;工欲善其事&#xff0c;必先利其器。作为每天和各种开发工具打交道的程序…
阅读更多...
编写规范的readme文件

编写规范的readme文件

为什么要写这篇博客&#xff1f; 其实我是一个入坑已经半年的程序员&#xff0c;因为不是计算机专业&#xff0c;只能自己摸索&#xff0c;所以我深知博客的重要性。每次我的学习笔记啊&#xff0c;项目的&#xff0c;面试题啊&#xff0c;有的&#xff0c;只要有时间&#xff…
阅读更多...
如何写好github上的README

如何写好github上的README

项目名称&#xff08;超大字体或者是图片形式&#xff09; 这里再写一句骚气又精准的话描述你的项目吧 上手指南 写几句这样的话概括接下来的内容&#xff1a;以下指南将帮助你在本地机器上安装和运行该项目&#xff0c;进行开发和测试。关于如何将该项目部署到在线环境&…
阅读更多...
README.md编写

README.md编写

一、摘要 项目一般会有个描述文件&#xff0c;对于项目的代码来讲&#xff0c;这个描述就是README.md文件&#xff0c;可以描述各模块功能、目录结构等。该文件可以方便让人快速了解项目的代码结构和功能。当然&#xff0c;若要深层次的了解项目&#xff0c;就得看项目总体的需…
阅读更多...
GitHub上README.md编写教程（基本语法）

GitHub上README.md编写教程（基本语法）

主要参考&#xff1a;GitHub上README.md编写教程&#xff08;基本语法&#xff09;_无名的一棵小树-CSDN博客_readme.md语法 一、标题写法&#xff1a; 第一种方法&#xff1a;标题文本下方加“”号或“--”号 1、在文本下面加上等于号“” &#xff0c;那么上方的文本就变成…
阅读更多...
README.md文件

README.md文件

引言&#xff1a; README.md文件用的是Markdown编写的&#xff0c;所有我们先来看看Markdown的语法 首先在github上面某个项目里面创建一个README.md,然后在里面区编辑内容&#xff0c;如图&#xff0c; 点击edit file在下面输入内容&#xff0c;然后切换到preview changes进…
阅读更多...
GitHub上README.md教程

GitHub上README.md教程

最近对它的README.md文件颇为感兴趣。便写下这贴&#xff0c;帮助更多的还不会编写README文件的同学们。 README文件后缀名为md。md是markdown的缩写&#xff0c;markdown是一种编辑博客的语言。用惯了可视化的博客编辑器&#xff08;比如CSDN博客&#xff0c;囧&#xff09;&a…
阅读更多...
README文档的规范写法

README文档的规范写法

看过很多开源库&#xff0c;发现有些库的文档写的一团糟&#xff0c;有的甚至就是一个标题&#xff0c;让你自己下载之后运行&#xff0c;自己摸索&#xff0c;看的很头疼。而那些使用量大的库的文档写的很标准&#xff0c;很详细&#xff0c;看的很舒服。 README文档写的好的…
阅读更多...
你真的知道README吗？

你真的知道README吗？

目录 README MarkDown README的要素 API文档 总结 README是我们开发项目必备的文件&#xff0c;之前没有认真的研究过&#xff0c;都是大概的了解下&#xff0c;没想到里面也是一门大学问&#xff0c;话不多说&#xff0c;直接码起来。 README README是项目自我描述文件…
阅读更多...
软件项目规范（1）：README文件的基本写作规范

软件项目规范（1）：README文件的基本写作规范

看Github的开源项目&#xff0c;我们都能看到README.md文件的身影。 有不少同学都喜欢将自己的项目上传到Git托管起来&#xff0c;但是总能发现一个问题&#xff1a;明明自己这个项目挺有市场的啊&#xff0c;怎么这个代码放上去&#xff0c;就显得很“非官方”&#xff01; …
阅读更多...
Java基础-快速入门

Java基础-快速入门

Java基础 Java基础-快速入门java简介java介绍java版本为什么学习javajava特点java优缺点优点缺点 java应用范围适用于不适用于 java规范java平台 安装JDK第一个Java程序安装并使用EclipseEclipse介绍Eclipse安装使用Eclipse创建第一个项目 安装Eclipse插件 Java基础-快速入门 …
阅读更多...
Java-基础入门

Java-基础入门

1.发展历史 1995年Sun公司发布Java1.0版本 1997年发布Java1.1版本 1998年发布Java1.2版本 2000年发布Java1.3版本 2002年发布Java1.4版本 2004年发布Java1.5版本 2006年发布Java1.6版本 2009年Oracle甲骨文公司收购Sun公司&#xff0c;并于2011发布Java1.7版本 2014年…
阅读更多...
java入门笔记

java入门笔记

1. Java相关概念 编程&#xff1a;用倾向于自然语言的方式编写指令代码的过程 编译&#xff1a;将自然语言指令代码转化为机器语言&#xff08;二进制&#xff09;的过程系统差异化&#xff1a;为了用不同类型的芯片实现相同的功能&#xff0c;就需要用不同的指令代码操作不同…
阅读更多...
一、Java基础入门

一、Java基础入门

一、java简介 1.1 前言 Java语言是美国Sun公司(stanford University Network),在1995年推出的高级编程语言。所谓编程语言是计算机的语言&#xff0c;人们可以使用编程语言对计算机下达命令&#xff0c;让计算机完成人们需要的功能。 1996年1月&#xff0c;Sun公司发布了Java的…
阅读更多...
Java基础及入门

Java基础及入门

一、软件开发基础 1.什么是JavaEE JavaEE是一门接收来自客户端的请求&#xff0c;并通过响应返回给客户端数据的技术。 2.JavaEE理解图 2.常用的开发语言 二、Java开发环境搭建 1.什么是JDK及JRE 安装JRE的目的是什么&#xff1f;&#xff08;是为了编译代码&#xff09; JDK&…
阅读更多...
java入门的基础（入门必读）

java入门的基础（入门必读）

Java入门基础 什么是java程序开发Java的运行环境开发Java程序的步骤java的基本框架数据类型、变量数据类型变量变量名命名规则 运算符关系运算符逻辑运算符算术运算符 扫描仪的使用if选择结构多重if选择结构嵌套if选择结构 switch选择结构循环结构while循环结构do-while循环结构…
阅读更多...
JAVA基础学习入门

JAVA基础学习入门

JAVA入门之基本语法&#xff08;一&#xff09; 最近开始复习JAVA语言为找工作做准备&#xff0c;方便以后再次复习或者用到的时候回顾。先是从JAVA的基本语法学起&#xff0c;因为有c和c语言的基础知识铺垫&#xff0c;所以这部分的笔记会比较粗略&#xff0c;毕竟语言都是贯…
阅读更多...
Java基础入门（六）

Java基础入门（六）

Java基础入门&#xff08;六&#xff09; 1 Debug调试1.1 Debug概述1.2 Debug操作流程1.2.1 设置断点1.2.2 运行加了断点的程序1.2.3 Debugger窗口和Console窗口1.2.4 分步执行1.2.5 取消断点1.2.6 结束Debug1.2.7 注意事项 2.基础中常用的类2.1 Random随机数2.2 Scanner获取用…
阅读更多...
推荐文章

Copyright @ 2022~2023