Standard Readme: a spec, a badge, and a generator for README files
A standard style for README files
At a glance
- What is it?
- RichardLitt/standard-readme defines a README format rather than a tool you run. The spec is free to follow, the linter is still a work in progress, and the only installable piece is a small package that prints the spec to your console.
- Who is it for?
- Adopt it if you maintain a library whose README keeps drifting between contributors, or if you need one structure across many repositories, which is the problem the author describes from maintaining IPFS repositories. Skip it if your README is a landing page for a product, or if you expect a working linter: the README links to the linter as a work in progress, so nothing in this repository checks your file automatically.
- 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 1 day 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 September 30, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What Standard Readme fixes, and who it is written for
A README is the first entry point to a codebase, and most projects write it once and then let it rot. Standard Readme attacks that by fixing the structure instead of the prose. The repository holds a specification in spec.md, an example README that is itself compliant, a folder of further examples, and a badge. The README states the goal plainly: standardizing how you write a README makes creating and maintaining READMEs easier.
The intended audience is narrow and stated: open source libraries. The README notes that the project historically came out of Node and npm work but applies to libraries in other languages and package managers. It is not aimed at application READMEs, marketing pages, or monorepo top-level docs. The origin story is concrete. The idea came from an issue raised by @maxogden on feross/standard, discussion moved through zcei's standard-readme repository, and the author needed a way to standardize READMEs across IPFS repositories. That is a maintainer-at-scale problem, not a first-project problem: one person enforcing one shape across dozens of repositories.
The spec is the product; the tooling is thin
The mechanism is editorial, not programmatic. You read spec.md, you arrange your README into the sections it names, and you optionally add the badge. Nothing parses your file unless you bring a separate tool. The repository's own README doubles as the reference implementation, which is a useful property: the table of contents, Background, Install, Usage, Badge, Example READMEs, Related Efforts, Maintainers, Contributing and License sections are all visible in one file you can copy.
Two supporting pieces live outside this repository. The generator is at RichardLitt/generator-standard-readme, and the README says that package exposes a global executable aliased as standard-readme. The linter is at RichardLitt/standard-readme-preset, and the README labels it a work in progress and links to a tracking issue. That distinction matters if you are evaluating this for a CI pipeline: the specification is stable enough to have shipped v1.3.0, but automated conformance checking is explicitly unfinished.
The package in this repository is a documentation package. Its package.json declares one binary, standard-readme, mapped to cat.js, and its dependencies are opencollective and opencollective-postinstall, with a postinstall script that runs opencollective-postinstall. So installing it pulls in a funding prompt, not a parser.
Installing the spec printer and running it once
You do not need to install anything to follow the specification. The README says so directly. If you want the spec on your machine, the project uses node and npm, and the documented install is a global one:
npm install --global standard-readme-specThe package name is standard-readme-spec even though the binary is standard-readme. After the install, running the binary prints the specification to your console:
standard-readmeWhat you should see is the contents of spec.md. That is the whole first use: read the output, then compare it against your existing README. If you would rather scaffold a new file than edit an old one, the README points to the generator package instead, which provides a global executable also aliased as standard-readme. The badge is optional and the README gives the Markdown to paste:
[](https://github.com/RichardLitt/standard-readme)The README recommends placing badges near the top and warns that too many badges clutter the page.
Where Standard Readme is the wrong tool
The linter gap is the first real limitation. The README calls it a work in progress and links to an open tracking issue, so there is no supported command in this repository that fails a build when a README drifts out of spec. If your requirement is enforcement, you are buying a convention and supplying the enforcement yourself.
The second limitation is scope. The specification assumes a library with an installable artifact, because the Install and Usage sections are structural. A CLI tool, a service with no package, or a documentation site does not map cleanly onto that skeleton, and filling those sections with filler is worse than omitting them. The README's own framing, that it is designed for open source libraries, is the honest boundary.
The third is that a fixed section order is a cost as well as a benefit. The README quotes Ken Williams: the documentation, not the code, defines what a module does. A rigid order serves a reader who arrives knowing the convention. A reader who does not will still scan for the word Install, so the ordering buys consistency more than discoverability.
Finally, the install carries a postinstall script that invokes opencollective-postinstall. Some teams block postinstall scripts in CI or in locked-down environments, and that is a friction point the README does not discuss.
How this differs from Art of Readme and plain templates
The README lists two related efforts: noffle/art-of-readme and davidbgk/open-source-template. The difference in approach is worth stating precisely. Art of Readme is guidance about writing quality READMEs, so it teaches judgement and leaves structure to the author. open-source-template is a README template aimed at encouraging open-source contributions, so it gives you a starting file to edit. Standard Readme does neither of those things exactly: it publishes a numbered specification with named sections, plus a badge that asserts compliance, plus a generator that scaffolds the file to match. The claim to compliance is the distinguishing feature. A template cannot be violated; a specification can, which is what makes a badge meaningful and what makes the missing linter conspicuous.
Maintenance, licence and upgrade cost
The repository is not archived, and the last push was on 2026-06-17. The most recent release is v1.3.0, dated 2026-03-18, following 1.2.2 in 2024. That release rhythm suggests the specification changes slowly, which is appropriate for a document that other projects copy into their repositories.
The practical upgrade cost is low but not zero. If you follow the specification by hand, a new revision means re-reading spec.md and adjusting sections; nothing breaks automatically because nothing is wired in. If you depend on the generator or the preset, those are separate repositories with their own release cycles, and the README does not document how they track spec versions.
The licence is MIT, declared in package.json and present as LICENSE in the repository root. MIT is permissive: it allows reuse and modification with the licence and copyright notice retained. That is a statement about the licence text, not advice about your situation. One thing worth noting for anyone copying the badge: the badge links back to this repository, and the README says the badge is not required, so removing it is not a compliance failure.
Editorial conclusion
Adopt it if you maintain a library whose README keeps drifting between contributors, or if you need one structure across many repositories, which is the problem the author describes from maintaining IPFS repositories. Skip it if your README is a landing page for a product, or if you expect a working linter: the README links to the linter as a work in progress, so nothing in this repository checks your file automatically. Before you commit, read spec.md itself, since that file and not the README is the normative document, and confirm which sections your project can honestly fill.
Frequently asked questions
What is meant by README?
The project treats the README as the first entry point to your code, and says it should tell people why they should use your module, how to install it, and how to use it. Standard Readme exists to fix the shape of that file rather than its wording.
Why do I have a file that says README?
The README explains that your README file is normally the first entry point to your code, which is why projects ship one at the repository root. Standard Readme's own README is a compliant example of that file.
Should README be MD or TXT?
Standard Readme does not address the file extension directly. Its specification, its example READMEs and its translated spec are all Markdown files, and the badge snippet it publishes is Markdown, so the convention it demonstrates is .md.
What makes a good README?
The README says a good one tells people why they should use your module, how they can install it, and how they can use it. It quotes Ken Williams to make the stronger point that the documentation, not the code, defines what a module does.
Official sources
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.
[](https://hysenlabs.com/projects/richardlitt-standard-readme)