othneildrew/Best-README-Template: a Markdown scaffold with shields, TOC and back-to-top links

The problem it solves: a README skeleton you edit instead of write

Most README templates are prose you have to reformat. This one is a layout. The README states the author's reasoning directly: "There are many great README templates available on GitHub; however, I didn't find one that really suited my needs so I created this enhanced one." The result is a single Markdown file with a fixed section order (About The Project, Built With, Getting Started with Prerequisites and Installation, Usage, Roadmap, Contributing, License, Contact, Acknowledgments) plus a collapsible table of contents built from an HTML details element.

The audience is narrow and clear. It is for someone publishing a repository on GitHub who wants the structural parts done: a back-to-top anchor, a table of contents, a badge row, and a place for a screenshot. It is not for someone who wants the README written for them. Every section in the template is filled with example content that has to be replaced, and the README says so in places, for instance "This is an example of how you may give instructions on setting up your project locally."

How the template is put together: anchors, reference links and a details block

Two mechanisms carry most of the file. The first is a named anchor. The README opens with an HTML comment noting that the placement is for "Improved compatibility of back to top link", followed by an anchor tag with the id readme-top. Each section then ends with a paragraph containing a link back to that id. The comment references a pull request that changed the anchor position, which tells you the placement was adjusted for a rendering problem rather than chosen arbitrarily.

The second is reference-style links. The badge row uses bracketed labels such as contributors-shield and contributors-url, and the URL definitions are collected at the bottom of the document. The README explains the choice: "I'm using markdown reference style links for readability. Reference links are enclosed in brackets [ ] instead of parentheses ( )." The practical effect is that the badge row stays short and the URLs are edited in one place.

The table of contents is an HTML details element wrapping an ordered list of anchor links, with nested lists under About The Project and Getting Started. That is what makes it collapsible on GitHub. The repository also ships BLANK_README.md alongside README.md, and the README points there: "Use the BLANK_README.md to get started." The README does not describe what BLANK_README.md omits, so you have to open it to find out.

Installing and using othneildrew/Best-README-Template

There is nothing to install in the package-manager sense. The template has no runtime and no build step; the README states plainly that it "doesn't rely on any external dependencies or services." Getting started means copying the file into your own repository.

The README's own installation example is written for a project that consumes the template, so the commands below are the ones it shows. The first step clones a repository, which in the template's example is a placeholder path:

git clone https://github.com/github_username/repo_name.git

After cloning, the README's example installs NPM packages. That step belongs to the example project the template is demonstrating, not to the template itself, so skip it unless your own project needs it:

npm install

The README's example then stores a credential in a JavaScript file, with the value left as a placeholder string:

const API_KEY = 'ENTER YOUR API';

The step most people miss is the last one. If you cloned the template repository and started editing, your origin still points at the base project. The README addresses this directly and gives the fix plus a verification command:

git remote set-url origin github_username/repo_name
git remote -v # confirm the changes

What you should see after that is your own repository in both the fetch and push lines of the output. Then open BLANK_README.md, delete the sections your project does not have, and replace the badge URLs at the bottom of the file with your own.

Where it stops being the right tool

The template gives you one shape and expects you to cut it down. That is fine for an application repository with a screenshot, prerequisites and a roadmap. It is a poor fit for a library whose README is mostly API reference, or for a monorepo where each package needs its own entry point, because the structure assumes a single product page.

There is a second limitation in the file itself. The badge row and the Built With section are populated with other projects: Next.js, React, Vue, Angular, Svelte, Laravel, Bootstrap and JQuery, each with a reference-style URL. Those are examples, and leaving them in is the most common way a README built from this template looks wrong. The same applies to the placeholder links to example.com and the placeholder screenshot.

The roadmap section is worth reading before you commit to the template. It lists "Add Additional Templates w/ Examples" and "Add "components" document to easily copy & paste sections of the readme" as unchecked items, and multi-language support with Chinese and Spanish sub-items also unchecked. So the per-section copy-paste workflow and the extra templates are planned, not shipped. If you need either today, this template does not have it. The README also does not document a rollback or an upgrade path for projects already using an older copy.

What to use instead when you want generation, not a skeleton

The related searches people run against this project include "GitHub readme-template generator", and that phrasing points at a different category of tool. A generator asks you questions and emits a filled README; this template hands you an empty structure and stops. The difference shows up the first time you update: with a generator you often re-run it, while with this template you edit the Markdown in place forever.

If your goal is a profile-level README on your GitHub user page rather than a repository README, that is also a different artifact. The template is a project page: it has an Installation section, a Prerequisites section and a Roadmap. A profile README has none of those, so you would be deleting most of the file. The search list separates the two, listing "GitHub profile readme template" apart from "Simple readme template", and the distinction is real.

If you want something simpler than this template, the honest answer is that this template already contains a simpler version of itself: BLANK_README.md. Starting there and adding only the sections you need is a legitimate alternative to adopting the full README.md.

Maintenance, licence and the cost of staying current

The repository is not archived, and the last push was on 2026-04-18. The most recent release listed is v1.1.2 from 2024-12-07, preceded by v1.1.1 on 2024-08-10. That is a slow cadence, which is reasonable for a Markdown file and unreasonable if you were hoping for the roadmap items to land soon.

Upgrade cost is close to zero by design. Because the template has no dependencies and no build step, adopting a newer revision means diffing your README against the upstream file and taking the structural changes you want, such as the back-to-top anchor placement. The risk is the reverse of a normal dependency: your README has diverged, so an upstream change to the badge row or the table of contents will not merge cleanly.

The licence is the Unlicense, and the repository ships LICENSE.txt and a license badge. The Unlicense is a public-domain dedication rather than a permissive licence with attribution conditions, which is why the template can be copied without carrying a notice. That is a description of the licence text, not legal advice; read LICENSE.txt if the distinction matters to your organisation.

Editorial conclusion

Use it if you want a README skeleton with a fixed section order and reference-style badge links, and you are willing to delete the placeholder text yourself. Do not use it if you need generated output, multi-language support or a per-project section picker: the README lists those under Roadmap as unchecked items. Before adopting it, open BLANK_README.md and confirm it is the stripped version you want to edit, then set your own git remote with git remote set-url origin github_username/repo_name so the template repository is not your push target.

Frequently asked questions

Official sources

1. Issues
2. License: Unlicense
3. othneildrew/Best-README-Template on GitHub
4. README
5. Releases