readme-best-practices: a README template you fetch with a single curl command

Seven fixed sections and one file to copy

readme-best-practices is a place to copy-paste your README.md from. The premise is simple enough to state in a sentence: the README is one of the most important files in an open source project, the author argues, and instead of writing one from scratch every time, you take a prepared one and fill in the blanks.

What is actually in the repository is very little. The top-level entries are the LICENSE file, README-default.md, README.md, an assets directory and a sample logo image. There is no code, no build pipeline, no test suite and no package manifest. The whole project is a document.

The document is a template with seven ready-made sections: Installing, Developing, Features, Configuration, Contributing, Links and Licensing. The demo image in the README makes the point plainly, showing a project with an empty README.md running one curl command to fetch README-default.md, then filling in the blanks and pushing with git.

Seven sections is a deliberate number rather than a maximal one. A template with twenty headings would push every project towards documenting things it does not have, and the resulting README would read like a form rather than an introduction. Seven covers the questions a newcomer reliably asks, which is how the template earns its place.

The author is also honest about the limits of the approach. As the project is used for the author's own work, it might not be the perfect approach for all projects out there, and contributors are invited to open an issue with ideas about what could be better.

Getting the template into your repository with curl

The getting started flow has three stages, and each one has a stated purpose.

The first copies the template into your project as README.md:

curl https://raw.githubusercontent.com/jehna/readme-best-practices/master/README-default.md > README.md

The explanation is that the code above fetches the README-default.md file from this repository and renames it to README.md. The redirection into README.md is what does the renaming, and the raw.githubusercontent.com path is what serves the file without a page of HTML around it.

The second command opens the result for editing:

code README.md

The README notes that if you are using VS Code, this opens the file for editing, and that if necessary you should substitute it with your preferred markdown editor. That substitution matters more than it sounds, since the template is markdown with embedded sections, and a comfortable editor is where you will actually spend the time filling it in.

The third stage is git. The instructions are to add the file, commit it and push it:

git add README.md
git commit -m "Added: README"
git push

That adds the README.md file to your git repository, creates a commit for it and pushes it to GitHub or your preferred remote repository.

The whole sequence is worth noting for what it does not do. It does not check anything, does not compare your README against the template later, and does not warn when a section is empty. The template is a starting point handed over once, and after that it is an ordinary file in your repository.

The guiding text has to be replaced, not just skimmed

The README is explicit about the work remaining after the copy. The default template has some guiding text to get you started, and you need to edit the file with your own text to use it with your project.

That is the whole catch, and it is where the value of the project is won or lost. A template with placeholder prose still in place is worse than no template, because it looks finished. Someone reading the repository sees headings that promise configuration or development instructions and finds the template's suggestions underneath.

The template is therefore best understood as a set of prompts rather than a set of sentences. Each heading asks a question that the project has to answer: how do I install this, how do I work on it locally, what does it do, what can I configure, how do people contribute, where else can I find things, and under what terms is it published. A project with no configuration surface can drop that heading, and a project with no contribution process should not claim one.

The README lists three goals for what the project makes it easy to do: bootstrap your open source project properly, make sure everyone gets what you are trying to achieve with your project, and follow simple instructions for a perfect README.md.

The middle one is the real goal. A README is the first thing a user reads, and the template's job is to make sure that first read answers the question of what this project is for and how to use it.

There is a small logo file in the repository as well, sample-logo.png, which is the kind of asset that a template usually offers for the header of the document.

README-yourplatform.md as a convention for variants

The contributing section contains an escape hatch that is more interesting than it first appears.

The author acknowledges that the vision of a perfect README may differ greatly from one project to another, and that this might be because the projects are vastly different. In that case, you can create a new file named README-yourplatform.md and create the perfect boilerplate for that.

The example given is concrete: if you have a perfect README for a Grunt project, just name it as README-grunt.md.

So the convention is that a variant template lives in the same repository as the default, named README- followed by the platform or audience it targets. That gives you a small library of ready-made documents in one place, each of which you copy into the right kind of project.

The advantage over maintaining separate repositories is that the variants stay in one directory and can be corrected together. The limitation is equally clear: the platform dimension is a filename convention, not a selection mechanism. Nothing in the getting started flow will pick README-grunt.md for you when you clone a Grunt project, because the tool does not know what kind of project you are in. The selection stays a manual copy.

That is consistent with the rest of the project. It is a collection of documents and a convention for organising them, not a generator with a config file.

The Unlicense and the difference between a template and a tool

The licensing section states that the project is licensed under an Unlicense license, and adds the point that this license does not require you to take the license with you to your project.

That is worth pausing on, because it is unusual for a template. Most template projects ship with a permissive licence such as MIT or Apache-2.0 and ask you to keep the notice. Under the Unlicense as described here, the template text itself carries no requirement to travel with the project that uses it. The Unlicense is the project-wide licence, with the licence text in the LICENSE file at the repository root, and the README makes the practical point for anyone who copies from it.

The second thing to understand is what kind of artefact this is. The repository has no releases, and its top-level contents are a licence, two README files, an assets directory and a logo image. There is nothing to install, nothing to configure, and nothing to run.

The consequence is that quality here depends on the copy. A team that adopts the template gets a good starting structure and nothing more. There is no linting of the resulting README, no check that the sections match the project, no CI step that fails when a section is stale, and no tooling that keeps a fork of the template in sync with the original. The README does not describe any of those, and their absence is the honest boundary of the project.

For a documentation-standards problem in a small organisation, a convention and a document are often enough. For a team that wants the structure enforced across many repositories, this repository is a starting point to write, not a finished system.

Where to look for other starting points

The project lists related projects under a heading for other places to find inspiration for creating the best possible README.

Four are named. Billie Thompson's README template, a list of awesome READMEs, Akash Nimare's kickass README guide, and Dan Bader's README template. Each is linked from the README itself.

This list does real work for the reader who finds the default template does not fit their project. A README is a genre with strong conventions and a lot of existing examples, and the difference between a good and a weak README is often a matter of which headings a particular community expects. The related list gives four different starting points with different emphases, which is more useful than a single template for a project that has to serve a specific audience.

For the project itself, the contribution route is documented in the usual form: open an issue to discuss an idea, or fork and send a pull request, which the README says are warmly welcome. Combined with the README-yourplatform.md convention, that gives two ways to contribute beyond improving the default file, one of which is to add a variant rather than change what everyone gets.

On maintenance, the repository is not archived, the last push was on 2026-06-07, and there are no GitHub releases. For a repository whose entire content is a document, that is a reasonable signal: changes to the template are visible in the diff of the file itself, and there is no versioned artefact for a consumer to pin to.

Editorial conclusion

Adopt readme-best-practices when you are starting a repository and want a README skeleton that already answers the questions a newcomer asks, and when a consistent house style matters more than a bespoke structure. Skip it if your project documentation already exists, or if you need the template to be enforced rather than suggested, because nothing here checks the README after it is written. Before using it, read the seven section headings in README-default.md and delete the ones your project genuinely does not need, and check the licence file, since the project is offered under the Unlicense and the README states it does not require you to take the licence with you.

Frequently asked questions

Official sources

1. Issues
2. jehna/readme-best-practices on GitHub
3. License: Unlicense
4. README