Open-source project
RichardLitt/standard-readme avatar
RichardLitt/standard-readme

The manifest is at 1.3.1 and the newest tag is v1.3.0

A standard style for README files

6,395 stars2,498 forksJavaScriptMIT

At a glance

What is it?
standard-readme is a specification document with one executable wrapped around it, plus a linter and a generator that live in other repositories. What the repository itself contains is thin: a bin entry pointing at cat.js, a manifest with no dependencies, and two languages of the same spec.
Who is it for?
Adopt this if you want a fixed section order to argue about and a document to point contributors at; skip it if you need a linter today, because the one the page advertises is in another repository and labelled work in progress. Three things are worth checking before you depend on any of it.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 47 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • RichardLitt/standard-readme6,395 ★ · +26
Star history
Repository2026-09-232026-11-15
RichardLitt/standard-readme6.4k6.4k

26 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The manifest sits one version ahead of the newest tag

package.json declares version 1.3.1. The newest release is v1.3.0, dated 2026-03-18, and the one before it is 1.2.2, dated 2024-05-09. Two facts sit in those three strings. The manifest is ahead of the newest tag, which is the ordinary shape for a repository whose version is bumped before the release is cut. The tag naming is also inconsistent, since one release carries a v prefix and the other does not, so a changelog sorted by tag name will not order them correctly. The last commit on the default branch is dated 2026-09-29, six months after the newest tag, which is a long gap for a package whose whole content is prose. The package name is standard-readme-spec while the repository is standard-readme, so the thing you install is not named after the thing you read.

The command is cat.js, and the generator claims the same command name

The manifest's only executable is one entry: the bin name standard-readme mapped to cat.js, a single script at the top of the tree. The usage section describes what running it does in two lines, where the command is followed by a comment saying it prints out the standard-readme spec, and the prose above it says the package is only a documentation package whose spec.md you can print to your console.

sh
$ npm install --global standard-readme-spec

So the install pulls in an executable that exists to output a markdown file. The naming collision is in the next subsection: the generator, which lives in a separate repository, has its own global executable also aliased as `standard-readme`. Both installed globally, the two packages want the same command name, and the page does not say which one wins or how to avoid the clash. The README also notes that nothing needs to be installed at all to follow the specification, which is true of a document and slightly at odds with the install line in the same section.

The badge to copy is an empty link, while the text credits Shields.io

The badge section explains that compliant projects on GitHub are welcome to add one so readers can link back to the specification, and says plainly that the badge is not required. It also states the badge uses Shields.io, a service for generating customizable badges. The page then gives a Markdown snippet to paste that links back to https://github.com/RichardLitt/standard-readme. The surrounding advice is sound and specific: put badges near the top so important project information is immediately visible, and avoid adding too many because a crowded row reduces readability.

The same five deliverables are listed twice, in different orders

Open the page and the contents arrive as a five-item numbered list: the specification in spec.md, a link to a linter in another repository marked work in progress, a link to a generator in a third repository, a badge, and a folder of examples that includes the page itself. Scroll to the goals and the same five subjects come back as another five-item list: a well defined specification described as a constant work in progress whose changes should be discussed in issues, an example README said to be fully compliant, a linter with the same pointer to a tracking issue, a generator, and the compliant badge. Two lists, one set of deliverables, and a difference worth noticing: the linter is described as work in progress in the first and simply referred to the tracking issue in the second. The examples folder is described as containing more than the page you are reading.

A remark config and a lockfile ship with a manifest that declares no dependencies

The tree holds a .remarkrc, a package-lock.json, a CITATION.cff, a FUNDING.yml and cat.js. package.json declares none of the usual surrounding work: no dependencies, no devDependencies, no scripts block, no main, no files list, no exports. What it does declare is the bin entry, a repository url, a keywords list of nine terms, an author with an email address and a personal site, MIT as the license, an issues url, a homepage pointing back at the repository, and opencollective as the funding route, which lines up with the FUNDING.yml file beside it. A remark configuration with no remark dependency declared is the odd pairing: markdown lint settings exist in the tree, but nothing in the manifest says what reads them or which version. The manifest also carries a coordinates entry holding a pair of numbers in the 52 and 13 ranges, a geographic field with no obvious bearing on a document package.

Two languages of the spec ship, and the command has one documented output

The tree lists README.md and README.zh-CN.md, and spec.md and spec.zh-CN.md, so the specification exists in English and Chinese side by side, as does the page describing the project. The usage section documents a single command with a single result, printing spec.md to your console, and neither the prose nor the bin entry offers an option, an argument or a second executable name for the other file. Nothing in this repository says how the Chinese spec is produced or kept in step; the contributor section asks for issues and pull requests and points at a code of conduct, version 1/3/0 of the Contributor Covenant. With two copies of a living document and one hard-coded print path, the question of which file a reader sees is settled by the command rather than by a preference.

The specification calls itself a constant work in progress

The first of the five goals states that the specification is a constant work in progress and asks for issues to discuss changes, which is an unusual thing for the primary deliverable of a project to say about itself. The page reinforces the reasoning with a quotation attributed to Ken Williams of Perl Hackers, in which documentation is complete when someone can use the module without ever looking at its code, and in which the documentation rather than the code defines what a module does. The stated benefit follows from that: because the documented interface is separated from the implementation, the internals can change while the interface holds. The page also names its audience twice, as open source libraries generally and as historically made for Node and npm projects while still applying to libraries in other languages and package managers. The specification is thus the product, and it is the part most likely to change under you.

The origin story runs through three other repositories and two related efforts

The background section traces the idea to an issue originally posed by maxogden in the feross/standard repository, asking whether a tool to standardize readmes would be useful at all. It says a lot of that discussion ended up in the zcei/standard-readme repository, and that the specification started as the result of the author's own need while maintaining the IPFS repositories, where standardizing readmes across an organization was the problem to solve. The same paragraph ends with the argument for the whole approach: writing readmes is hard, keeping them maintained is harder, and offloading the process should leave more time for writing and using code. A related efforts section points at two other projects by name, an Art of Readme and an open-source template for encouraging contributions, neither of which is a linter or a generator and neither of which is described further than its one-line summary.

Editorial conclusion

Adopt this if you want a fixed section order to argue about and a document to point contributors at; skip it if you need a linter today, because the one the page advertises is in another repository and labelled work in progress. Three things are worth checking before you depend on any of it. The manifest says 1.3.1, while the newest release is v1.3.0 from 2026-03-18 and older tags are not all prefixed the same way, so tag names will not sort for you. The command name is claimed twice, once by this package and once by the generator in its own repository, which matters if you install both globally. And the badge is optional: the README says it is not required.

Frequently asked questions

What is standard-readme for, if the deliverable is a document?

It is a specification plus one executable. The install line is npm install --global standard-readme-spec, and the bin entry maps the command standard-readme to cat.js, so the package exists so you can print the spec rather than lint a README. Nothing has to be installed to follow the specification itself.

Does standard-readme ship a linter today?

Not in this repository. The page links a linter preset hosted separately and labels it work in progress, pointing at a tracking issue, and the goals list points at that same issue for the linter goal.

Which standard-readme version should I expect from the registry?

The manifest on the default branch says 1.3.1, while the newest release tag is v1.3.0 dated 2026-03-18 and the one before it is 1.2.2 without the v prefix. The package is published under the name standard-readme-spec rather than standard-readme.

Is there a Chinese version of the standard-readme specification?

The tree holds spec.zh-CN.md beside spec.md, and README.zh-CN.md beside README.md. The usage section documents one command that prints spec.md, with no documented flag or argument for the other file.

What makes a good README, according to standard-readme?

The page says a README is the first entry point to your code and should tell people why they should use the module, how they can install it, and how they can use it. It quotes the rule that the documentation, not the code, defines what a module does.

Why does installing both the standard-readme spec and its generator cause trouble?

Both want the same global command name. This package maps standard-readme to cat.js, and the generator's own repository documents a global executable also aliased as standard-readme, so installing both leaves two packages contending for one executable.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. RichardLitt/standard-readme on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/richardlitt-standard-readme.svg)](https://hysenlabs.com/projects/richardlitt-standard-readme)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/richardlitt-standard-readme.svg)](https://hysenlabs.com/projects/richardlitt-standard-readme)

Was this useful?