├── cat.sh ├── .remarkrc ├── example-readmes ├── minimal-readme.md └── maximal-readme.md ├── .gitignore ├── LICENSE ├── package.json ├── README.zh-CN.md ├── spec.zh-CN.md ├── README.md └── spec.md /cat.sh: -------------------------------------------------------------------------------- 1 | #! /bin/bash 2 | 3 | cat spec.md 4 | -------------------------------------------------------------------------------- /.remarkrc: -------------------------------------------------------------------------------- 1 | { 2 | "plugins": { 3 | "remark-title": { 4 | "title": "IPFS Readme Standard" 5 | } 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /example-readmes/minimal-readme.md: -------------------------------------------------------------------------------- 1 | # Title 2 | 3 | This is an example file with default selections. 4 | 5 | ## Install 6 | 7 | ``` 8 | ``` 9 | 10 | ## Usage 11 | 12 | ``` 13 | ``` 14 | 15 | ## Contributing 16 | 17 | PRs accepted. 18 | 19 | ## License 20 | 21 | MIT © Richard McRichface 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | 5 | # Runtime data 6 | pids 7 | *.pid 8 | *.seed 9 | 10 | # Directory for instrumented libs generated by jscoverage/JSCover 11 | lib-cov 12 | 13 | # Coverage directory used by tools like istanbul 14 | coverage 15 | 16 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 17 | .grunt 18 | 19 | # node-waf configuration 20 | .lock-wscript 21 | 22 | # Compiled binary addons (http://nodejs.org/api/addons.html) 23 | build/Release 24 | 25 | # Dependency directory 26 | # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git 27 | node_modules 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2017-2019 Richard Littauer 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "standard-readme-spec", 3 | "version": "1.2.2", 4 | "description": "A standard style for README files", 5 | "bin": "cat.sh", 6 | "repository": { 7 | "type": "git", 8 | "url": "git+https://github.com/RichardLitt/standard-readme.git" 9 | }, 10 | "keywords": [ 11 | "standard", 12 | "markdown", 13 | "readme", 14 | "parse", 15 | "lint", 16 | "standard-readme", 17 | "spec", 18 | "md", 19 | "documentation" 20 | ], 21 | "author": { 22 | "name": "Richard Littauer", 23 | "email": "richard.littauer@gmail.com", 24 | "url": "http://burntfen.com" 25 | }, 26 | "license": "MIT", 27 | "bugs": { 28 | "url": "https://github.com/RichardLitt/standard-readme/issues" 29 | }, 30 | "homepage": "https://github.com/RichardLitt/standard-readme", 31 | "dependencies": { 32 | "opencollective": "^1.0.3", 33 | "opencollective-postinstall": "^2.0.3" 34 | }, 35 | "coordinates": [ 36 | 52.5173031, 37 | 13.4535065 38 | ], 39 | "collective": { 40 | "type": "opencollective", 41 | "url": "https://opencollective.com/standard-readme" 42 | }, 43 | "scripts": { 44 | "postinstall": "opencollective-postinstall" 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /example-readmes/maximal-readme.md: -------------------------------------------------------------------------------- 1 | # Title 2 | 3 | ![banner]() 4 | 5 | ![badge]() 6 | ![badge]() 7 | [![license](https://img.shields.io/github/license/:user/:repo.svg)](LICENSE) 8 | [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 9 | 10 | This is an example file with maximal choices selected. 11 | 12 | This is a long description. 13 | 14 | ## Table of Contents 15 | 16 | - [Security](#security) 17 | - [Background](#background) 18 | - [Install](#install) 19 | - [Usage](#usage) 20 | - [API](#api) 21 | - [Contributing](#contributing) 22 | - [License](#license) 23 | 24 | ## Security 25 | 26 | ### Any optional sections 27 | 28 | ## Background 29 | 30 | ### Any optional sections 31 | 32 | ## Install 33 | 34 | This module depends upon a knowledge of [Markdown](). 35 | 36 | ``` 37 | ``` 38 | 39 | ### Any optional sections 40 | 41 | ## Usage 42 | 43 | ``` 44 | ``` 45 | 46 | Note: The `license` badge image link at the top of this file should be updated with the correct `:user` and `:repo`. 47 | 48 | ### Any optional sections 49 | 50 | ## API 51 | 52 | ### Any optional sections 53 | 54 | ## More optional sections 55 | 56 | ## Contributing 57 | 58 | See [the contributing file](CONTRIBUTING.md)! 59 | 60 | PRs accepted. 61 | 62 | Small note: If editing the Readme, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. 63 | 64 | ### Any optional sections 65 | 66 | ## License 67 | 68 | [MIT © Richard McRichface.](../LICENSE) 69 | -------------------------------------------------------------------------------- /README.zh-CN.md: -------------------------------------------------------------------------------- 1 | # 标准 Readme 2 | 3 | [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 4 | 5 | 标准 Readme 样式 6 | 7 | README 文件是人们通常最先看到的第一个东西。它应该告诉人们为什么要使用、如何安装、以及如何使用你的代码。README 文件标准化能够使得创建和维护 README 文件更加简单。毕竟，要写好一个文档不是那么容易的。 8 | 9 | 本仓库包含以下内容： 10 | 11 | 1. 一个标准的 README 文件应该是什么样子的[规范](spec.md)。 12 | 2. 一个用于维护 README 文件的语法提示工具的链接 ([正在进行中](https://github.com/RichardLitt/standard-readme/issues/5))。 13 | 3. 一个创建标准 README 的[生成器](https://github.com/RichardLitt/generator-standard-readme)。 14 | 4. 一个指向该规范的[徽章](#徽章)。 15 | 5. [标准 README 的实例](example-readmes/) - 比如你正在读的这个文件。 16 | 标准 Readme 是为了开源组件设计的。尽管它的[背景](#背景)是为了服务于 Node 和 npm 项目, 它同时也可以应用到其他编程语言和包管理器中去。 17 | 18 | ## 内容列表 19 | 20 | - [背景](#背景) 21 | - [安装](#安装) 22 | - [使用说明](#使用说明) 23 | - [生成器](#生成器) 24 | - [徽章](#徽章) 25 | - [示例](#示例) 26 | - [相关仓库](#相关仓库) 27 | - [维护者](#维护者) 28 | - [如何贡献](#如何贡献) 29 | - [使用许可](#使用许可) 30 | 31 | ## 背景 32 | 33 | `标准 Readme` 最开始因为 [@maxogden](https://github.com/maxogden) 在项目 [feross/standard](https://github.com/feross/standard) 的[这个 Issue](https://github.com/feross/standard/issues/141) 中提出，是否标准化 README 会有助于帮助大家。很多人在仓库 [zcei's standard-readme](https://github.com/zcei/standard-readme/issues/1) 就这个想法进行了讨论。在我维护仓库 [IPFS](https://github.com/ipfs) 的时候，我需要在这个组织中推广标准化的 Readme，因此这个项目也就从这开始了。 34 | 35 | > 如果你的文档是完整的，那么使用你代码的人就不用再去看代码了。这非常的重要。它使得你可以分离接口文档与具体实现。它意味着你可修改实现的代码而保持接口与文档不变。 36 | 37 | > 请记住：是文档而非代码，定义了一个模块的功能。 38 | 39 | —— [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document) 40 | 41 | 写 README 从某种程度上来说相当不易，一直维护下去更是难能可贵。如果可以减少这个过程，则可以让写代码与修改代码更容易，使得是否在说明中指明一处需改有无必要更加清楚，你可以花费更少的时间来考虑是否你最初的文档是否需要更新，你可以分配更多的时间来写代码而非维护文档。 42 | 43 | 同时，标准化在某些别的地方也有好处。有了标准化，用户就可以花费更少的时间来搜索他们需要的信息，他们同时可以做一个工具来从描述中搜集信息，自动跑示例代码，检查授权协议等等。 44 | 45 | 这个仓库的目标是： 46 | 47 | 1. 一个定义良好的**规范**。在仓库中的位置是 [spec.md](spec.md)。它是一个一直在持续优化的文档，欢迎您提 Issue 讨论其中的变化。 48 | 2. 一个**示例 README**。这个 Readme 完全遵从 Standard-readme，而且在 `example-readmes` 文件夹里有更多的示例。 49 | 3. 一个**语法提示器**用来提示在 Readme 中的语法错误。请参考 [tracking issue](https://github.com/RichardLitt/standard-readme/issues/5)。 50 | 4. 一个**生成器**用来快速搭建新的 README 的框架。请参考 [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme)。 51 | 5. 一个**标识准守规范的徽章**。请参考[徽章](#徽章)。 52 | 53 | ## 安装 54 | 55 | 这个项目使用 [node](http://nodejs.org) 和 [npm](https://npmjs.com)。请确保你本地安装了它们。 56 | 57 | ```sh 58 | $ npm install --global standard-readme-spec 59 | ``` 60 | 61 | ## 使用说明 62 | 63 | 这只是一个文档包，你可以打印出 [spec.md](spec.md) 到输出窗口。 64 | 65 | ```sh 66 | $ standard-readme-spec 67 | # Prints out the standard-readme spec 68 | ``` 69 | 70 | ### 生成器 71 | 72 | 想要使用生成器的话，请看 [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme)。 73 | 有一个全局的可执行文件来运行包里的生成器，生成器的别名叫 `standard-readme`。 74 | 75 | ## 徽章 76 | 如果你的项目遵循 Standard-Readme 而且项目位于 Github 上，非常希望你能把这个徽章加入你的项目。它可以更多的人访问到这个项目，而且采纳 Stand-README。 加入徽章**并非强制的**。 77 | 78 | [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 79 | 80 | 为了加入徽章到 Markdown 文本里面，可以使用以下代码： 81 | 82 | ``` 83 | [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 84 | ``` 85 | 86 | ## 示例 87 | 88 | 想了解我们建议的规范是如何被应用的，请参考 [example-readmes](example-readmes/)。 89 | 90 | ## 相关仓库 91 | 92 | - [Art of Readme](https://github.com/noffle/art-of-readme) — 💌 写高质量 README 的艺术。 93 | - [open-source-template](https://github.com/davidbgk/open-source-template/) — 一个鼓励参与开源的 README 模板。 94 | 95 | ## 维护者 96 | 97 | [@RichardLitt](https://github.com/RichardLitt)。 98 | 99 | ## 如何贡献 100 | 101 | 非常欢迎你的加入！[提一个 Issue](https://github.com/RichardLitt/standard-readme/issues/new) 或者提交一个 Pull Request。 102 | 103 | 104 | 标准 Readme 遵循 [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) 行为规范。 105 | 106 | ### 贡献者 107 | 108 | 感谢以下参与项目的人： 109 | 110 | 111 | 112 | ## 使用许可 113 | 114 | [MIT](LICENSE) © Richard Littauer 115 | -------------------------------------------------------------------------------- /spec.zh-CN.md: -------------------------------------------------------------------------------- 1 | # 规范 2 | 3 | 一个兼容的 README 必须满足下面列出的所有需求。 4 | 5 | 6 | > 注意: 标准自述文件是为开放源码库设计的。 尽管它[以前](README.cn.md#背景)是为 Node 和 npm 项目制作的，但它也适用于其他语言的库和包管理器。 7 | 8 | **要求:** 9 | - 被叫做 README.md (大写). 10 | - 如果项目支持 i18n，文件名必须相应地命名: `README.de.md`, `de` 是 BCP 47语言标记. 对于命名，优先考虑语言的非区域子标记. 如果只有一个 README，并且语言不是英语，那么文本中允许使用不同的语言，而无需指定 BCP 标记: 例如: `README.md` 如果没有语言 README 的话，可以用德语 `README.md`. 在有多种语言的地方,README.md 是留给英语的. 11 | - 做一个正确的 Markdown 文件. 12 | - 部分必须按照下面给出的顺序显示。可以省略选择部分. 13 | - 除非另有说明，部分必须有下面列出的标题。 如果 README 是另一种语言，则必须将标题翻译成该语言. 14 | - 不能包含失效的链接. 15 | - 如果有代码示例，那么它们的连接方式应该与项目其余部分的代码连接方式相同. 16 | 17 | ## 目录 18 | 19 | _注意: 这只是规范的建议，并没有为任何符合规范的文档定义或强制要求使用术语。_ 20 | 21 | - [段落](#段落) 22 | - [标题](#标题) 23 | - [横幅](#横幅) 24 | - [徽章](#徽章) 25 | - [简短描述](#简短描述) 26 | - [长描述](#长描述) 27 | - [目录](#目录-1) 28 | - [安全](#安全) 29 | - [背景](#背景) 30 | - [安装](#安装) 31 | - [用法](#用法) 32 | - [额外部分](#额外部分) 33 | - [API](#api) 34 | - [维护者](#维护者) 35 | - [致谢](#致谢) 36 | - [如何贡献](#如何贡献) 37 | - [许可证](#许可证) 38 | - [定义](#定义) 39 | 40 | ## 段落 41 | 42 | ### 标题 43 | **状态:** 必须 44 | 45 | 46 | **要求:** 47 | 48 | - 标题必须与仓库、文件夹和包管理器名称相匹配——或者用斜体和括号表示的相关副标题。 例如: 49 | 50 | ```markdown 51 | # Standard Readme Style _(standard-readme)_ 52 | ``` 53 | 如果任何文件夹、仓库或包管理器名称不匹配，必须在“长描述”中附注说明原因。 54 | 55 | **建议:** 56 | 57 | - 应该是有据可循的 58 | 59 | ### 横幅 60 | **状态:** 可选 61 | 62 | **要求:** 63 | - 不能有自己的标题 64 | - 必须链接到当前存储库中的本地映像 65 | - 必须直接出现在标题后面 66 | 67 | ### 徽章 68 | **Status:** 可选. 69 | 70 | **要求:** 71 | - 不能有自己的标题 72 | - 必须用换行符分隔 73 | 74 | **建议:** 75 | - 使用 http://shields.io 或类似的服务来创建和托管图像 76 | - 添加 Standard Readme badge 徽章. 77 | 78 | ### 简短描述 79 | **状态:** 必须 80 | 81 | **要求:** 82 | - 不能有自己的标题 83 | - 必须少于120个字符 84 | - 不能以 `>` 开始 85 | - 一定是在它自己的行上 86 | - 必须符合包管理器的`描述`字段 87 | - 必须符合 GitHub 的描述(如果在 GitHub 上) 88 | 89 | **建议:** 90 | - 使用[gh-description](https://github.com/RichardLitt/gh-description) 描述设置并获取 GitHub 描述 91 | - 使用`npm show . description` 来展示本地的描述 [npm](https://npmjs.com) 包 92 | 93 | ### 长描述 94 | **状态:** 可选 95 | 96 | **要求:** 97 | - 不能有自己的标题 98 | - 如果任何文件夹、存储库或包管理器名称不匹配，则必须在这里说明原因。 看标题部分 99 | 100 | **建议:** 101 | - 如果太长，考虑移动到背景部分。 102 | - 包含构建储存库的主要原因。 103 | 104 | - “这应该大致地描述你的模块，通常只有几个段落; 模块的例程或方法的更多细节，冗长的代码示例，或其他深入的材料应该在随后的章节中给出。 105 | 理想情况下，对您的模块稍微熟悉的人应该能够刷新他们的记忆，而不必按下“页面向下”键。 当你的读者继续阅读文档时，他们应该会接收到越来越多的知识。” 106 | 107 | ~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html) 108 | 109 | ### 目录 110 | **状态:** 必需的; 对于小于100行的 README 可选。 111 | **要求:** 112 | - 必须链接到文件中的所有 Markdown 部分 113 | - 必须从下一节开始，不要包括标题或目录标题 114 | - 必须至少有一个深度: 必须捕获所有 `##` 标题 115 | 116 | **建议:** 117 | - 可以捕获第三个和第四个深度标题。如果是长目录，这些是可选的. 118 | 119 | ### 安全 120 | **状态:** 可选. 121 | 122 | **要求:** 123 | - 如果需要强调安全问题，可以在这里，否则应该在`额外`部分. 124 | 125 | ### 背景 126 | **状态:** 可选 127 | 128 | **要求:** 129 | - 包含动机. 130 | - 包含抽象依赖关系. 131 | - 包含知识来源: `可参见`也很合适. 132 | 133 | ### 安装 134 | **状态:** 默认情况下是必需的，文档存储库是可选的. 135 | 136 | **要求:** 137 | - 说明如何安装的代码块 138 | 139 | **子段落:** 140 | - 如果有不寻常的依赖项或依赖项，必须手动安装 141 | 142 | **建议:** 143 | -链接到编程语言的必备站点: [npmjs](https://npmjs.com), [godocs](https://godoc.org),等等. 144 | - 包括安装所需的任何系统特定信息. 145 | - 一个`更新`部分对大多数软件包都很有用, 如果用户可以使用多个版本. 146 | 147 | ### 用法 148 | **状态:** 默认情况下是必需的，文档存储库是可选的. 149 | 150 | **要求:** 151 | - 说明常用用法的代码块. 152 | - 如果 CLI 兼容，则代码块指示通用用法. 153 | - 如果可导入，则指示导入功能和用法的代码块. 154 | 155 | **建议:** 156 | - `CLI`. 如果 CLI 功能存在，则需要. 157 | 158 | **建议:** 159 | - 涵盖可能影响使用的基本选项: 例如，如果是 JavaScript，则涵盖 promises / callbacks，此处为 ES6 160 | - 如果相关，指向一个可运行的文件以获取使用代码 161 | 162 | ### 额外部分 163 | **状态:** 可选. 164 | 165 | **要求:** 166 | - 没有. 167 | 168 | **建议:** 169 | - 这不应该被称为额外部分. 这是一个包含0个或更多部分的空间，每个部分都必须有自己的标题 170 | - 这应该包含任何其他相关的部分,放在用法之后, API 之前. 171 | - 具体来说，就是, 安全部分如果没有重要到可以放在上面的话，这个部分应该在这里. 172 | 173 | ### API 174 | **状态:** 可选 175 | 176 | **要求:** 177 | - 描述暴露出的功能和对象. 178 | 179 | **建议:** 180 | - 描述签名、返回类型、回调和事件. 181 | - 指明不容易理解的类型. 182 | - 描述注意事项. 183 | - 如果使用外部 API 生成器(比如 go-doc、 js-doc 等等) ，请指向外部 API.md 文件. 这可能是该节中的唯一项，如果存在的话 184 | 185 | ### 维护者 186 | **状态:** 可选. 187 | 188 | **要求:** 189 | - 一定要叫维护者 190 | - 列出存储库的维护人员，以及与他们联系的一种方式(例如 GitHub 链接或电子邮件). 191 | 192 | **建议:** 193 | - 这应该是一个负责项目方向的人员名单。 这不应该是拥有访问权限的每个人，比如整个组织，应该被展示的人是负责存储库的指导和维护的人 194 | - 列出过去的维护人员对于属性和分类都有好处. 195 | 196 | ### 致谢 197 | **状态:** 可选. 198 | 199 | **要求:** 200 | - 一定要叫做 致谢 或者 感谢. 201 | 202 | **建议:** 203 | - 说明对项目的开发有重要帮助的任何人或任何事情 204 | - 标明公共链接，如果适用的话 205 | 206 | ### 如何贡献 207 | **状态:** 必需. 208 | 209 | **要求:** 210 | - 说明用户可以提问的地方. 211 | - 说明是否接受 PR . 212 | - 列出贡献的所有要求; 例如，在提交时有一个签名. 213 | 214 | **建议:** 215 | - 链接到`如何贡献文件`--如果有的话 216 | - 尽可能友好 217 | - 链接到 GitHub issues 区域. 218 | - 链接到行为守则. `如何贡献规范`通常位于贡献部分或文档中,或者位于整个组织的其他位置，因此可能不需要在每个存储库中包含整个文件。 但是，强烈建议始终链接到规范位置，无论它位于何处. 219 | - 这里也欢迎列出贡献者的子段落. 220 | 221 | ### 许可证 222 | **状态:** 必须 223 | 224 | **要求:** 225 | - 声明许可证全名或标识符, 参考[SPDX](https://spdx.org/licenses/) 许可证列表上的. 对于未授权的存储库, 添加 `UNLICENSED`. 更多详情，请参见 `SEE LICENSE IN ` 并链接到许可文件. (这些要求是从 [npm](https://docs.npmjs.com/files/package.json#license)继承过来的). 226 | - 声明许可证持有人. 227 | - 一定是最后一部分. 228 | 229 | **建议:** 230 | - 链接到本地存储库中较长的许可证文件 231 | 232 | ## 定义 233 | 234 | _提供这些定义是为了澄清上面使用的任何术语._ 235 | 236 | - **文档存储库: 没有任何功能代码的存储库** 237 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Standard Readme 2 | 3 | [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 4 | 5 | A standard style for README files 6 | 7 | Your README file is normally the first entry point to your code. It should tell people why they should use your module, how they can install it, and how they can use it. Standardizing how you write your README makes creating and maintaining your READMEs easier. Great documentation takes work! 8 | 9 | This repository contains: 10 | 11 | 1. [The specification](spec.md) for how a standard README should look. 12 | 2. A link to [a linter](https://github.com/RichardLitt/standard-readme-preset) you can use to keep your README maintained ([work in progress](https://github.com/RichardLitt/standard-readme/issues/5)). 13 | 3. A link to [a generator](https://github.com/RichardLitt/generator-standard-readme) you can use to create standard READMEs. 14 | 4. [A badge](#badge) to point to this spec. 15 | 5. [Examples of standard READMEs](example-readmes/) - such as this file you are reading. 16 | 17 | Standard Readme is designed for open source libraries. Although it’s [historically](#background) made for Node and npm projects, it also applies to libraries in other languages and package managers. 18 | 19 | 20 | ## Table of Contents 21 | 22 | - [Background](#background) 23 | - [Install](#install) 24 | - [Usage](#usage) 25 | - [Generator](#generator) 26 | - [Badge](#badge) 27 | - [Example Readmes](#example-readmes) 28 | - [Related Efforts](#related-efforts) 29 | - [Maintainers](#maintainers) 30 | - [Contributing](#contributing) 31 | - [License](#license) 32 | 33 | ## Background 34 | 35 | Standard Readme started with the issue originally posed by [@maxogden](https://github.com/maxogden) over at [feross/standard](https://github.com/feross/standard) in [this issue](https://github.com/feross/standard/issues/141), about whether or not a tool to standardize readmes would be useful. A lot of that discussion ended up in [zcei's standard-readme](https://github.com/zcei/standard-readme/issues/1) repository. While working on maintaining the [IPFS](https://github.com/ipfs) repositories, I needed a way to standardize Readmes across that organization. This specification started as a result of that. 36 | 37 | > Your documentation is complete when someone can use your module without ever 38 | having to look at its code. This is very important. This makes it possible for 39 | you to separate your module's documented interface from its internal 40 | implementation (guts). This is good because it means that you are free to 41 | change the module's internals as long as the interface remains the same. 42 | 43 | > Remember: the documentation, not the code, defines what a module does. 44 | 45 | ~ [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document) 46 | 47 | Writing READMEs is way too hard, and keeping them maintained is difficult. By offloading this process - making writing easier, making editing easier, making it clear whether or not an edit is up to spec or not - you can spend less time worrying about whether or not your initial documentation is good, and spend more time writing and using code. 48 | 49 | By having a standard, users can spend less time searching for the information they want. They can also build tools to gather search terms from descriptions, to automatically run example code, to check licensing, and so on. 50 | 51 | The goals for this repository are: 52 | 53 | 1. A well defined **specification**. This can be found in the [Spec document](spec.md). It is a constant work in progress; please open issues to discuss changes. 54 | 2. **An example README**. This Readme is fully standard-readme compliant, and there are more examples in the `example-readmes` folder. 55 | 3. A **linter** that can be used to look at errors in a given Readme. Please refer to the [tracking issue](https://github.com/RichardLitt/standard-readme/issues/5). 56 | 4. A **generator** that can be used to quickly scaffold out new READMEs. See [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme). 57 | 5. A **compliant badge** for users. See [the badge](#badge). 58 | 59 | ## Install 60 | 61 | This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed. 62 | 63 | ```sh 64 | $ npm install --global standard-readme-spec 65 | ``` 66 | 67 | ## Usage 68 | 69 | This is only a documentation package. You can print out [spec.md](spec.md) to your console: 70 | 71 | ```sh 72 | $ standard-readme-spec 73 | # Prints out the standard-readme spec 74 | ``` 75 | 76 | ### Generator 77 | 78 | To use the generator, look at [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme). There is a global executable to run the generator in that package, aliased as `standard-readme`. 79 | 80 | ## Badge 81 | 82 | If your README is compliant with Standard-Readme and you're on GitHub, it would be great if you could add the badge. This allows people to link back to this Spec, and helps adoption of the README. The badge is **not required**. 83 | 84 | [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 85 | 86 | To add in Markdown format, use this code: 87 | 88 | ``` 89 | [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) 90 | ``` 91 | 92 | ## Example Readmes 93 | 94 | To see how the specification has been applied, see the [example-readmes](example-readmes/). 95 | 96 | ## Related Efforts 97 | 98 | - [Art of Readme](https://github.com/noffle/art-of-readme) - 💌 Learn the art of writing quality READMEs. 99 | - [open-source-template](https://github.com/davidbgk/open-source-template/) - A README template to encourage open-source contributions. 100 | 101 | ## Maintainers 102 | 103 | [@RichardLitt](https://github.com/RichardLitt). 104 | 105 | ## Contributing 106 | 107 | Feel free to dive in! [Open an issue](https://github.com/RichardLitt/standard-readme/issues/new) or submit PRs. 108 | 109 | Standard Readme follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) Code of Conduct. 110 | 111 | ### Contributors 112 | 113 | This project exists thanks to all the people who contribute. 114 | 115 | 116 | 117 | ## License 118 | 119 | [MIT](LICENSE) © Richard Littauer 120 | -------------------------------------------------------------------------------- /spec.md: -------------------------------------------------------------------------------- 1 | # Specification 2 | 3 | A compliant README must satisfy all the requirements listed below. 4 | 5 | > Note: Standard Readme is designed for open source libraries. Although it's [historically](README.md#background) made for Node and npm projects, it also applies to libraries in other languages and package managers. 6 | 7 | **Requirements:** 8 | - Be called README.md (with capitalization). 9 | - If the project supports i18n, the file must be named accordingly: `README.de.md`, where `de` is the BCP 47 Language tag. For naming, prioritize non-regional subtags for languages. If there is only one README and the language is not English, then a different language in the text is permissible without needing to specify the BCP tag: e.g., `README.md` can be in German if there is no `README.md` in another language. Where there are multiple languages, `README.md` is reserved for English. 10 | - Be a valid Markdown file. 11 | - Sections must appear in order given below. Optional sections may be omitted. 12 | - Sections must have the titles listed below, unless otherwise specified. If the README is in another language, the titles must be translated into that language. 13 | - Must not contain broken links. 14 | - If there are code examples, they should be linted in the same way as the code is linted in the rest of the project. 15 | 16 | ## Table of Contents 17 | 18 | _Note: This is only a navigation guide for the specification, and does not define or mandate terms for any specification-compliant documents._ 19 | 20 | - [Sections](#sections) 21 | - [Title](#title) 22 | - [Banner](#banner) 23 | - [Badges](#badges) 24 | - [Short Description](#short-description) 25 | - [Long Description](#long-description) 26 | - [Table of Contents](#table-of-contents-1) 27 | - [Security](#security) 28 | - [Background](#background) 29 | - [Install](#install) 30 | - [Usage](#usage) 31 | - [Extra Sections](#extra-sections) 32 | - [API](#api) 33 | - [Maintainers](#maintainers) 34 | - [Thanks](#thanks) 35 | - [Contributing](#contributing) 36 | - [License](#license) 37 | - [Definitions](#definitions) 38 | 39 | ## Sections 40 | 41 | ### Title 42 | **Status:** Required. 43 | 44 | **Requirements:** 45 | - Title must match repository, folder and package manager names - or it may have another, relevant title with the repository, folder, and package manager title next to it in italics and in parentheses. For instance: 46 | 47 | ```markdown 48 | # Standard Readme Style _(standard-readme)_ 49 | ``` 50 | 51 | If any of the folder, repository, or package manager names do not match, there must be a note in the [Long Description](#long-description) explaining why. 52 | 53 | **Suggestions:** 54 | - Should be self-evident. 55 | 56 | ### Banner 57 | **Status:** Optional. 58 | 59 | **Requirements:** 60 | - Must not have its own title. 61 | - Must link to local image in current repository. 62 | - Must appear directly after the title. 63 | 64 | ### Badges 65 | **Status:** Optional. 66 | 67 | **Requirements:** 68 | - Must not have its own title. 69 | - Must be newline delimited. 70 | 71 | **Suggestions:** 72 | - Use http://shields.io or a similar service to create and host the images. 73 | - Add the [Standard Readme badge](https://github.com/RichardLitt/standard-readme#badge). 74 | 75 | ### Short Description 76 | **Status:** Required. 77 | 78 | **Requirements:** 79 | - Must not have its own title. 80 | - Must be less than 120 characters. 81 | - Must not start with `> ` 82 | - Must be on its own line. 83 | - Must match the description in the packager manager's `description` field. 84 | - Must match GitHub's description (if on GitHub). 85 | 86 | **Suggestions:** 87 | - Use [gh-description](https://github.com/RichardLitt/gh-description) to set and get GitHub description. 88 | - Use `npm show . description` to show the description from a local [npm](https://npmjs.com) package. 89 | 90 | ### Long Description 91 | **Status:** Optional. 92 | 93 | **Requirements:** 94 | - Must not have its own title. 95 | - 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](#title). 96 | 97 | **Suggestions:** 98 | - If too long, consider moving to the [Background](#background) section. 99 | - Cover the main reasons for building the repository. 100 | - "This should describe your module in broad terms, 101 | generally in just a few paragraphs; more detail of the module's 102 | routines or methods, lengthy code examples, or other in-depth 103 | material should be given in subsequent sections. 104 | 105 | Ideally, someone who's slightly familiar with your module should be 106 | able to refresh their memory without hitting "page down". As your 107 | reader continues through the document, they should receive a 108 | progressively greater amount of knowledge." 109 | 110 | ~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html) 111 | 112 | ### Table of Contents 113 | **Status:** Required; optional for READMEs shorter than 100 lines. 114 | 115 | **Requirements:** 116 | - Must link to all Markdown sections in the file. 117 | - Must start with the next section; do not include the title or Table of Contents headings. 118 | - Must be at least one-depth: must capture all `##` headings. 119 | 120 | **Suggestions:** 121 | - May capture third and fourth depth headings. If it is a long ToC, these are optional. 122 | 123 | ### Security 124 | **Status**: Optional. 125 | 126 | **Requirements:** 127 | - May go here if it is important to highlight security concerns. Otherwise, it should be in [Extra Sections](#extra-sections). 128 | 129 | ### Background 130 | **Status:** Optional. 131 | 132 | **Requirements:** 133 | - Cover motivation. 134 | - Cover abstract dependencies. 135 | - Cover intellectual provenance: A `See Also` section is also fitting. 136 | 137 | ### Install 138 | **Status:** Required by default, optional for [documentation repositories](#definitions). 139 | 140 | **Requirements:** 141 | - Code block illustrating how to install. 142 | 143 | **Subsections:** 144 | - `Dependencies`. Required if there are unusual dependencies or dependencies that must be manually installed. 145 | 146 | **Suggestions:** 147 | - Link to prerequisite sites for programming language: [npmjs](https://npmjs.com), [godocs](https://godoc.org), etc. 148 | - Include any system-specific information needed for installation. 149 | - An `Updating` section would be useful for most packages, if there are multiple versions which the user may interface with. 150 | 151 | ### Usage 152 | **Status:** Required by default, optional for [documentation repositories](#definitions). 153 | 154 | **Requirements:** 155 | - Code block illustrating common usage. 156 | - If CLI compatible, code block indicating common usage. 157 | - If importable, code block indicating both import functionality and usage. 158 | 159 | **Subsections:** 160 | - `CLI`. Required if CLI functionality exists. 161 | 162 | **Suggestions:** 163 | - Cover basic choices that may affect usage: for instance, if JavaScript, cover promises/callbacks, ES6 here. 164 | - If relevant, point to a runnable file for the usage code. 165 | 166 | ### Extra Sections 167 | **Status**: Optional. 168 | 169 | **Requirements:** 170 | - None. 171 | 172 | **Suggestions:** 173 | - 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. 174 | - This should contain any other sections that are relevant, placed after [Usage](#usage) and before [API](#api). 175 | - Specifically, the [Security](#security) section should be here if it wasn't important enough to be placed above. 176 | 177 | ### API 178 | **Status:** Optional. 179 | 180 | **Requirements:** 181 | - Describe exported functions and objects. 182 | 183 | **Suggestions:** 184 | - Describe signatures, return types, callbacks, and events. 185 | - Cover types covered where not obvious. 186 | - Describe caveats. 187 | - 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. 188 | 189 | ### Maintainer(s) 190 | **Status**: Optional. 191 | 192 | **Requirements:** 193 | - Must be called `Maintainer` or `Maintainers`. 194 | - List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email). 195 | 196 | **Suggestions:** 197 | - This should be a small list of people in charge of the repo. This should not be everyone with access rights, such as an entire organization, but the people who should be pinged and who are in charge of the direction and maintenance of the repository. 198 | - Listing past maintainers is good for attribution, and kind. 199 | 200 | ### Thanks 201 | **Status**: Optional. 202 | 203 | **Requirements:** 204 | - Must be called `Thanks`, `Credits` or `Acknowledgements`. 205 | 206 | **Suggestions:** 207 | - State anyone or anything that significantly helped with the development of your project. 208 | - State public contact hyper-links if applicable. 209 | 210 | ### Contributing 211 | **Status**: Required. 212 | 213 | **Requirements:** 214 | - State where users can ask questions. 215 | - State whether PRs are accepted. 216 | - List any requirements for contributing; for instance, having a sign-off on commits. 217 | 218 | **Suggestions:** 219 | - Link to a CONTRIBUTING file -- if there is one. 220 | - Be as friendly as possible. 221 | - Link to the GitHub issues. 222 | - 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. 223 | - A subsection for listing contributors is also welcome here. 224 | 225 | ### License 226 | **Status:** Required. 227 | 228 | **Requirements:** 229 | - State license full name or identifier, as listed on the [SPDX](https://spdx.org/licenses/) license list. For unlicensed repositories, add `UNLICENSED`. For more details, add `SEE LICENSE IN ` and link to the license file. (These requirements were adapted from [npm](https://docs.npmjs.com/files/package.json#license)). 230 | - State license owner. 231 | - Must be last section. 232 | 233 | **Suggestions:** 234 | - Link to longer License file in local repository. 235 | 236 | ## Definitions 237 | 238 | _These definitions are provided to clarify any terms used above._ 239 | 240 | - **Documentation repositories**: Repositories without any functional code. For instance, [RichardLitt/knowledge](https://github.com/RichardLitt/knowledge). 241 | --------------------------------------------------------------------------------