README.md template for a software project
Open in the editor Opens as README.md, ready to edit. Nothing is uploaded.
The shape of it — edit here, or open the full template
Result
Runs entirely in this tab. Open the full editor to work on a real document.
A README is the first thing anyone sees and usually the last thing anyone writes. This template is the structure that answers the questions people actually arrive with, in the order they arrive in.
The first screen does the work
Almost everyone who opens your README is deciding whether to keep reading. That decision is made from the title, the one-line description and the install command — so those three come first, before badges, before motivation, before the history of the project.
The one-liner is worth more effort than its length suggests. “A Markdown parser” describes a hundred projects. “A Markdown parser that keeps source positions, for building editors” describes exactly one, and the reader who needs it recognises themselves immediately.
The example has to run
The single most common README defect is an example that cannot be pasted and executed — it references a variable defined nowhere, or omits the import, or uses an API that changed two releases ago. Copy your own example into a scratch file and run it before you publish. Then do it again after any breaking change.
The API table
A table beats prose for anything with a default value, because readers scan rather than read:
| Parameter | Type | Default | Description |
|---|---|---|---|
input | string | — | The thing to process. Required. |
options.option | boolean | false | What this switches on. |
Right-aligning nothing and left-aligning everything is fine here; the columns
are all text. Use — rather than an empty cell for “no default”, so a required
parameter is visibly required rather than accidentally blank.
Contributing notes are a filter, not a formality
Two sentences saying “open an issue before a large PR” saves more time than a thousand-word code of conduct, because it redirects the effort that would otherwise be wasted. Add the clone-install-test sequence underneath so a contributor can get to a passing test suite without asking.
Badges are cheap and easy to overdo
Three or four earn their place: build status, licence, and the current version. Beyond that they become a wall of colour that readers learn to skip, taking the useful ones with them.
Common questions
- What should a README actually contain?
- What it does, how to install it, and one example that runs. Everything else is optional. Most abandoned READMEs fail at the example — a snippet that cannot be copied and run leaves the reader exactly where they started.
- Does the order of the sections matter?
- Yes, more than the content does. A reader scanning for "can I use this?" wants the one-line description and the install command in the first screen. Contributing guidelines and licence text belong at the bottom, where the people who need them will scroll.
- How do I add the status badges?
- They are ordinary Markdown images, usually wrapped in a link — an exclamation mark, the alt text in brackets, then the badge URL. This template includes two you can point at your own build and licence. They render as images anywhere that renders Markdown.
- Should a README have a table of contents?
- Only past about five sections. GitHub adds its own outline button, so a hand-maintained list of links is usually redundant and quietly goes stale. Long documentation sites are the exception.
- Why is it called README.md rather than README.txt?
- The .md marks it as Markdown, which is what lets GitHub, GitLab and npm render the headings and code blocks instead of showing raw punctuation. The name in capitals is a convention from Unix, where uppercase files sorted to the top of a directory listing.
- How do I preview it before pushing?
- Open it here. Drop your README.md onto the editor and the preview shows how it will render, without a commit or an upload. That is also the quickest way to catch a code fence you forgot to close.