Best-README-Template: the sections you inherit and the placeholders you keep

Reference style shields break if you copy only what you can see

The template's own comment explains the choice behind the badge row: it uses markdown reference style links, where links sit in brackets rather than parentheses, and points readers at https://www.markdownguide.org/basic-syntax/#reference-style-links for the syntax. Every badge in the header follows it:

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![Unlicense License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]

None of those names is defined where it is used. contributors-shield, forks-shield, license-url and the rest resolve against declarations the comment says sit at the bottom of the document, alongside the definition for contributors-url and forks-url.

That is the first trap for anyone adapting the file. Copy the block of shields you can see, stop there, and every badge image has nothing to point at. The rendered result looks like broken markup rather than a missing footer, which sends people hunting for a syntax error that is not there. Find the declaration block before concluding the shields are wrong.

The payoff for that indirection is that the header stays readable. Written inline, those six badges would bury the project name under six URLs. The same attention to inline noise explains the header comment at the very top of the file, which records the pull request that improved the compatibility of the back to top link.

BLANK_README.md is the starting point, README.md is the shop window

Two Markdown files sit at the top level. README.md is the worked example, carrying the badge row, the logo block, the table of contents and every section filled with illustrative text. BLANK_README.md is what the About The Project section points you at, in a single line: use the BLANK_README.md to get started.

Knowing that distinction saves an afternoon. README.md is dense with content that exists only to show the layout working. A product screenshot badge points at https://example.com. Built With carries eight framework badges from Next.js through React, Vue, Angular, Svelte, Laravel, Bootstrap and JQuery. The Getting Started section asks you to obtain a free API key from that same example domain, and Usage links to a Documentation page at https://example.com.

Start from README.md and you publish a repository whose front page advertises a service that does not exist, with a screenshot that resolves to a placeholder domain. Every one of those is a deliberate demonstration of a slot, and nothing in the file flags them as placeholders once the text is detached from its context.

CHANGELOG.md and LICENSE.txt accompany both files. LICENSE.txt holds the licence text, and the repository is dedicated to the public domain under that licence.

The Getting Started steps are illustration, and there is no package.json

This is where a new user loses the most time. The Prerequisites section tells you to install npm, and offers this:

npm install npm@latest -g

Installation then walks five steps. Obtain a free API key from https://example.com. Clone with git clone https://github.com/github_username/repo_name.git. Run npm install. Put the key into config.js:

const API_KEY = 'ENTER YOUR API';

then repoint the git remote so you cannot push to the base project.

None of it applies here, and the file says so in the sentence under its own Installation heading: this template doesn't rely on any external dependencies or services. The repository's top level holds .github/, .idea/, BLANK_README.md, CHANGELOG.md, LICENSE.txt, README.md and images/. There is no package.json, no config.js and no application to run, so npm install has nothing to install and the API key step has nothing to consume.

These are copy and paste material for the projects you build after adopting the template, not instructions for adopting it. Reading them as a setup guide can make the template appear to require Node tooling and an account on an example service. The repository has no build step and no runtime to install.

The table of contents is a details element, so it disappears where HTML is stripped

The navigation block is not plain Markdown. It is a details element with a summary reading Table of Contents, wrapping an ordered list that links to About The Project, Built With, Getting Started, Prerequisites, Installation, Usage, Roadmap, Contributing, License, Contact and Acknowledgments.

The choice buys a collapsed list on GitHub, which keeps the opening of a long README short and pushes the navigation out of the first screen. It costs portability. A renderer that strips HTML drops the whole block, anchors to Prerequisites and Installation included, and leaves a document the reader has to scroll. A renderer that honours details but ignores summary, or that opens every details element by default, keeps the links and changes the layout instead of removing it.

The same dependency runs through the rest of the file. A div with align center wraps the logo and the call to action, and each section ends with a paragraph holding a back to top link anchored to an id declared near the top of the document:

<a id="readme-top"></a>

Every section in the source finishes with that back to top paragraph. That anchor is why the compatibility pull request mentioned in the header comment matters. If your README is destined for a destination that renders Markdown without HTML, decide up front whether losing the navigation and every back to top link is a trade you can live with.

Placeholder keys and github_username remotes are what most copies keep

Two artefacts of the demonstration content survive more often than they should. The first is the config.js snippet carrying the literal string ENTER YOUR API, which lands in a committed file and then in whatever that file is bundled into. The second is the leftover remote URL, and the step that fixes it is the one genuinely useful instruction in the whole Installation section:

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

The comment on that step is right: changing the remote URL avoids accidental pushes to the base project. Fork any template and your origin still points at the repository you forked from, so a careless push aimed at origin goes to a stranger's repository. Run the first command, then read the output of the second to confirm the change took rather than assuming it did.

The visible symptom of a template copied without that step is the placeholder string itself. A repository whose README still contains github_username was cloned and never adapted. Checking your README for placeholder domains and placeholder usernames takes a minute and catches most forks that skipped the adaptation.

Three unchecked roadmap items and a last push that outran the last release

The Roadmap section tracks its own state with checkboxes. Two entries are ticked: add Changelog, and add back to top links. Three are not. Additional templates with examples. A components document, described as a way to easily copy and paste sections of the readme. And multi-language support, with Chinese and Spanish named as the first two.

Those three unchecked items are the difference between one template and a family of them. The components document in particular maps directly onto the gap the author names, that no one template will serve all projects since needs may be different. A library of pasteable sections would be the answer to that. It has not been built, so a project wanting a different section order has no official way to get one from here.

On maintenance, the two GitHub releases are v1.1.1 on 2024-08-10 and v1.1.2 on 2024-12-07, while the last push to the default branch was on 2026-04-18. The branch has moved since the last tag without a release to match. Pinning to a tag therefore hands you something older than the branch, and tracking the branch gives you changes with no version marker telling you what moved or when.

The same section promises a last ever template and concedes it cannot be

About The Project opens by saying many great README templates exist on GitHub, that none suited the author's needs, and that this enhanced one was built to fill the gap. It then states the ambition as a template so good it will be the last one you ever need. A few paragraphs later the same section concedes that no one template will serve all projects, because needs may be different.

Both statements are in the source, and reading them together tells you what kind of artefact this is: a considered default, not a framework. What it offers is section order, badge placement, a navigation block and a consistent back to top affordance. What it does not attempt is anything about your project, since it has no idea what your build process, your architecture or your release cadence look like. Even the Built With section admits its limits, telling you to leave add-ons and plugins for the acknowledgements section and offering eight framework badges purely as examples.

For an adopter the limit is precise. The section skeleton is the product. If you need a table of contents generated from your headings rather than maintained by hand, a licence layout matching your organisation, or a separate template per language, none of that is in this repository, and the roadmap entries that would have addressed it remain open.

Forking this template and writing your own README are both defensible

There is a real alternative to adopting it, and the difference is maintenance cost rather than the finished output.

Writing your own costs an afternoon and gives you markup that already matches your renderer, your section order and your badges, with no reference declarations to keep in step and no HTML to lose. You also inherit the parts nobody enjoys: deciding what belongs above the fold, keeping it true as the project changes, and stopping it from decaying into a wall of stale text.

Adopting the template costs a fork and gives you a structure strangers already recognise, which matters when the README's audience is people who have never seen your project. You take on replacing the placeholder content, keeping the badge declarations aligned with the badges you keep, and accepting that navigation and back to top links render only where HTML is allowed.

The Contributing section applies either way. Fork the project, create a feature branch with git checkout -b feature/AmazingFeature, commit with git commit -m 'Add some AmazingFeature', push with git push origin feature/AmazingFeature, then open a pull request. Suggestions go in as an issue tagged enhancement, and the header links straight to the issue form carrying that label.

Editorial conclusion

Use Best-README-Template when you want a section structure and badge header other people already recognise, and start from BLANK_README.md rather than README.md. Do not follow its Getting Started section literally, because the repository has no package.json and the npm steps are copy and paste material for the project you build afterwards. Before adopting, confirm your renderer keeps details and div elements, since the table of contents and the back to top links depend on HTML, and weigh the 2026-04-18 last push against the older v1.1.2 tag before pinning a version.

Frequently asked questions

Official sources

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