diff --git a/README.md b/README.md index 16f2fd5..07bd510 100644 --- a/README.md +++ b/README.md @@ -7,34 +7,19 @@ > Readme Standard Style -This repo is for standardizing how READMEs should look. The goal is to have a spec, a linter, a generator, a badge, and examples. +This repo is for standardizing how READMEs should look. The goal is to have a spec, a linter, a generator, a badge, and examples. This document is also an example of a standard README. ## Table of Contents - [Background](#background) - - [Goals:](#goals) + - [Goals](#goals) - [Installation](#installation) - [Usage](#usage) + - [Generator](#generator) - [Badge](#badge) -- [Specification](#specification) - - [Requirements](#requirements) - - [Sections](#sections) - - [Title](#title) - - [Banner](#banner) - - [Badges](#badges) - - [Short Description](#short-description) - - [Long Description](#long-description) - - [Table of Contents](#table-of-contents-1) - - [Security](#security) - - [Background Section](#background-section) - - [Installation](#installation-1) - - [Usage Section](#usage-section) - - [Extra Sections](#extra-sections) - - [API](#api) - - [Contribute](#contribute) - - [License](#license) -- [Contribute](#contribute-1) -- [License](#license-1) + - [Example Readmes](#example-readmes) +- [Contribute](#contribute) +- [License](#license) ## Background @@ -50,16 +35,16 @@ change the module's internals as long as the interface remains the same. ~ [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document) -### Goals: -1. A well defined **specification**. This can be found in the [Specification](#specification) section. It is a constant work in progress; please open issues to discuss changes. +### Goals +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. 2. **An example README**. This Readme is fully standard-readme compliant, and there are more examples in the `example-readmes` folder. 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). 4. A **generator** that can be used to quickly scaffold out new READMEs. See [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme). 5. A **compliant badge** for users. See [the badge](#badge). -## Installation +## Install -This project uses [node][] and [npm][]. Go check them out if you don't have them locally installed. +This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed. ```sh $ npm i -g standard-readme @@ -67,11 +52,11 @@ $ npm i -g standard-readme ## Usage -Currently, this is only a Readme spec. +Currently, this is only a README spec. ``` $ standard-readme -// Will output spec (this Readme) +// Will print spec.md to the console ``` ### Generator @@ -94,164 +79,6 @@ To add in Markdown format, use this code: To see how the specification has been applied, see the [example-readmes](example-readmes/). -## Specification - -### Requirements - -A compliant README must: - - Be called README.md (with capitalization). - - Be a valid Markdown file. - - Sections must appear in order delineated below. Optional sections may be omitted. - - Must be new lines between each section. - -**Suggestions:** -- A "Back to Top" link for longer sections can be useful, but is not required by any means. - -### Sections - -#### Title -**Status:** Required. -**Requirements:** -- Must match repository name. If it cannot, there must be a note in the long description about why. -- Must match package manager name. If it cannot, there must be a note in the long description about why. - -**Suggestions:** -- Should be self-evident. - -#### Banner -**Status:** Optional. -**Requirements:** -- Must link to local image in current repository. -- Must appear directly after the title. - -#### Badges -**Status:** Optional. -**Requirements:** -- Must be newline delimited. - -#### Short Description -**Status:** Required. -**Requirements:** -- Must be less than 120 characters. -- Must start with `> ` -- Must be on it's 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](https://github.com/RichardLitt/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 have no heading. - -**Suggestions:** -- If too long, consider moving to the [Background](#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." - - ~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html) - - -#### Table of Contents -**Status:** Required. -**Requirements:** -- Must link to all Markdown sections in the file. -- 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 visibility of security section is important. Otherwise, should be in [Extra Sections](#extra-sections). - -#### Background Section -**Status:** Optional. -**Requirements:** -- Cover motivation. -- Cover abstract dependencies. -- Cover intellecutal provenance: A `See Also` section is also fitting. - -#### Installation -**Status:** Required. -**Requirements:** -- Code block illustrating how to install. - -Subsections: -- `Dependencies`. Required if necessary. -- `Updating`. Optional. - -**Suggestions:** -- Link to prerequisite sites for language. [npmjs][], [godocs][], etc. -- Include any system-specific information needed for Installation. -- Subsection for dependencies needed for install to work. - -#### Usage Section -**Status:** Required. -**Requirements:** -- Code block illustrating common usage. -- If CLI compatible, code block indicating common usage. -- If importable, code block indicating both import functionality and usage. - -Subsections: -- `CLI`. Required if CLI functionality exists. -- If relevant, point to a runnable file for the usage code. - -**Suggestions:** -- Cover basic choices that may affect usage: for instance, if JavaScript, cover promises/callbacks, ES6 here. - -#### Extra Sections -**Status**: Optional. -**Requirements:** -- None. - -#### 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. - -#### Contribute -**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 `CONTRIBUTE.md` file -- if there is one. -- Be as friendly as possible. -- Link to the GitHub issues. -- Link to Code of Conduct. This is often in Contribute, or organization wide, so may not be necessary for each module. - -#### License -**Status:** Required. -**Requirements:** -- State license initials or name. -- State license owner. -- Must be last section. - -**Suggestions:** -- Link to longer License file in local repository. - ## Contribute Feel free to dive in! [Open an issue](https://github.com/RichardLitt/standard-readme/issues/new) or submit PRs. @@ -261,6 +88,3 @@ Standard Readme follows the [Contributor Covenant](http://contributor-covenant.o ## License MIT (c) Protocol Labs - -[node]: http://nodejs.org -[npm]: https://npmjs.com \ No newline at end of file diff --git a/index.js b/index.js index 83c15ad..0ffe762 100644 --- a/index.js +++ b/index.js @@ -1,5 +1,5 @@ var fs = require('graceful-fs') -var doc = 'README.md' +var doc = 'spec.md' fs.readFile(doc, { encoding: 'utf8' }, function(err, data) { console.log(data) diff --git a/spec.md b/spec.md new file mode 100644 index 0000000..19c3e09 --- /dev/null +++ b/spec.md @@ -0,0 +1,157 @@ +## Specification + +### Requirements + +A compliant README must: + - Be called README.md (with capitalization). + - Be a valid Markdown file. + - Sections must appear in order delineated below. Optional sections may be omitted. + - Must be new lines between each section. + +**Suggestions:** +- A "Back to Top" link for longer sections can be useful, but is not required by any means. + +### Sections + +#### Title +**Status:** Required. +**Requirements:** +- Must match repository name. If it cannot, there must be a note in the long description about why. +- Must match package manager name. If it cannot, there must be a note in the long description about why. + +**Suggestions:** +- Should be self-evident. + +#### Banner +**Status:** Optional. +**Requirements:** +- Must link to local image in current repository. +- Must appear directly after the title. + +#### Badges +**Status:** Optional. +**Requirements:** +- Must be newline delimited. + +#### Short Description +**Status:** Required. +**Requirements:** +- Must be less than 120 characters. +- Must start with `> ` +- Must be on it's 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](https://github.com/RichardLitt/gh-description) to set and get GitHub description. +- Use `npm show . description` to show the description from a local [npm](https://npmjs.com) package. + +#### Long Description +**Status:** Optional. +**Requirements:** +- Must have no heading. + +**Suggestions:** +- If too long, consider moving to the [Background](#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." + + ~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html) + + +#### Table of Contents +**Status:** Required. +**Requirements:** +- Must link to all Markdown sections in the file. +- 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 visibility of security section is important. Otherwise, should be in [Extra Sections](#extra-sections). + +#### Background Section +**Status:** Optional. +**Requirements:** +- Cover motivation. +- Cover abstract dependencies. +- Cover intellecutal provenance: A `See Also` section is also fitting. + +#### Install +**Status:** Required. +**Requirements:** +- Code block illustrating how to install. + +Subsections: +- `Dependencies`. Required if necessary. +- `Updating`. Optional. + +**Suggestions:** +- Link to prerequisite sites for language. [npmjs](https://npmjs.com), [godocs](https://godoc.org), etc. +- Include any system-specific information needed for Installation. +- Subsection for dependencies needed for install to work. + +#### Usage Section +**Status:** Required. +**Requirements:** +- Code block illustrating common usage. +- If CLI compatible, code block indicating common usage. +- If importable, code block indicating both import functionality and usage. + +Subsections: +- `CLI`. Required if CLI functionality exists. +- If relevant, point to a runnable file for the usage code. + +**Suggestions:** +- Cover basic choices that may affect usage: for instance, if JavaScript, cover promises/callbacks, ES6 here. + +#### Extra Sections +**Status**: Optional. +**Requirements:** +- None. + +#### 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. + +#### Contribute +**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 `CONTRIBUTE.md` file -- if there is one. +- Be as friendly as possible. +- Link to the GitHub issues. +- Link to Code of Conduct. This is often in Contribute, or organization wide, so may not be necessary for each module. + +#### License +**Status:** Required. +**Requirements:** +- State license initials or name. +- State license owner. +- Must be last section. + +**Suggestions:** +- Link to longer License file in local repository.