Markdown cheatsheet · README template
README template
A README answers three questions, in this order: what is this, how do I install it, how do I use it. Most of what makes a README bad is putting anything else first.
The template
Nine sections, in the order a reader actually needs them. Copy it, or download the file and start deleting what you don't need. Everything here is plain GitHub Flavored Markdown, covered in the cheatsheet.
# Project Name
One paragraph: what this does, who it is for, and why it exists.
Keep it under three sentences.
## Install
```bash
npm install project-name
```
## Usage
```js
import { greet } from "project-name";
const message = greet("world");
console.log(message);
```
## Options
| Option | Default | Description |
| --------- | ------- | ------------------------- |
| `timeout` | `5000` | Request timeout in ms |
| `retries` | `3` | Attempts before giving up |
## Contributing
Pull requests welcome. Open an issue first for anything larger
than a bug fix.
## License
MIT. See LICENSE for details.build passing
One paragraph: what this does, who it is for, and why it exists. Keep it under three sentences.
npm install project-nameimport { greet } from "project-name";
const message = greet("world");
console.log(message);| Option | Default | Description |
|---|---|---|
timeout | 5000 | Request timeout in ms |
retries | 3 | Attempts before giving up |
Pull requests welcome. Open an issue first for anything larger than a bug fix.
MIT. See LICENSE for details.
The order matters more than the content
Most bad READMEs aren't missing information. They're in the wrong order: three paragraphs of philosophy before the install command. A reader arrives with one of three questions, and they arrive in this sequence:
- What is this? One paragraph. If they can't tell in ten seconds, they leave.
- How do I install it? A command they can copy. Not a discussion of package managers.
- How do I use it? The smallest example that actually runs.
Everything else, configuration, contributing, licence, badges, architecture, is for the minority who got through those three and stayed. Put it below.
Variants
A Python project
Same structure, different commands. pip install project-name, an import block instead of a require, and a Requirements section naming the Python version, which Python users will look for and JS users won't.
A GitHub profile README
A different animal entirely. It lives in a repo named after your username and shows on your profile. It has no install section because it isn't software: it's an introduction. Structure it as a short bio, what you're working on, and how to reach you. Everything below "the order matters" still applies; the three questions are just different.
An application rather than a library
Swap Usage for Running it, add a screenshot near the top, and put configuration front and centre. For an app, the screenshot is the "what is this" paragraph, and it does the job faster than prose.
Badges, briefly
Those small status images come from a shield service; the markdown is an image whose URL is generated for you: . See images in markdown for the syntax.
Two or three that mean something (build status, version, licence) read as competence. Nine, including one for a chat room nobody has posted in since 2021, read as decoration. Each one is a line the reader has to skip to reach your first sentence.
What a README doesn't need
- A table of contents, unless the file is genuinely long. GitHub generates one from your headings, in the header of the rendered page. See table of contents.
- A changelog. That's
CHANGELOG.md. Keeping it in the README means every release edits the front page. - Full API documentation. If it's more than a table, it wants its own file or a docs site.
- An apology. "This is just a small project I hacked together" tells the reader not to rely on it. If you mean it, say what's unfinished, specifically.
Common questions
Does the file have to be called README.md?
To be rendered on a repo's front page, yes: GitHub looks for README.md (case-insensitive) at the root, or in .github/ or docs/. The name is a convention older than markdown itself.
Should I use a README generator?
They produce a filled-in skeleton, which beats an empty file. They also produce something that reads like a filled-in skeleton. Fine as a starting point, then rewrite the top paragraph in your own words: it's the only part most readers finish.
Will my README look the same everywhere?
Mostly. GitHub, GitLab and npm all render markdown but differ at the edges: GitHub Alerts don't render on npm, and raw HTML is filtered differently on each. Stick to the syntax in this template and it travels.
How long should it be?
Shorter than you think. If a reader has to scroll to find the install command, it's too long at the top, whatever the total.