README templates
Four templates for the four READMEs people actually write. Copy one, replace the placeholders, delete the sections you don't need — a README that omits a section beats one with “TODO” in it. Prefer filling in a form? The README generator builds one interactively with live badges.
General project README
The default — an app, a service, an internal tool. Answers the three reader questions in order: what is it, how do I run it, how do I work on it.
# Project Name One-sentence description of what this does and who it's for.  ## Features - The two or three things it does well - Written as outcomes, not implementation details ## Getting started ### Prerequisites - Node.js 20+ - A PostgreSQL database ### Installation ```bash git clone https://github.com/you/project cd project npm install cp .env.example .env # then fill in the values npm run dev ``` ## Usage Show the single most common workflow with a real example: ```bash npm run import -- --file data.csv ``` ## Configuration | Variable | Default | What it does | | -------- | ------- | ------------ | | `PORT` | `3000` | HTTP port | | `DATABASE_URL` | — | Postgres connection string | ## Contributing Pull requests welcome. Run `npm test` before submitting. ## License [MIT](LICENSE)
Open-source library / npm package
For code other people install. Leads with install + a working example — the two things every evaluating developer wants within ten seconds.
# package-name
[](https://www.npmjs.com/package/package-name)
[](https://github.com/you/package-name/actions)
[](LICENSE)
What it does in one sentence, and the problem it solves in one more.
## Install
```bash
npm install package-name
```
## Quick start
```js
import { thing } from 'package-name';
const result = thing('input');
// => what the reader should expect to see
```
## API
### `thing(input, options?)`
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `strict` | `boolean` | `false` | What it changes |
Returns a `Result`. Throws `TypeError` when input is not a string.
## Why not X?
One honest paragraph on how this differs from the popular alternative.
## License
MIT
CLI tool README
For command-line tools. The hero is a terminal session the reader can replay — show real commands with real output.
# mytool Fast one-line description. ```console $ mytool convert report.pdf ✔ Extracted 14 pages ✔ Wrote report.md (3,412 words) ``` ## Install ```bash # homebrew brew install mytool # or npm npm install -g mytool ``` ## Commands | Command | What it does | | ------- | ------------ | | `mytool convert <file>` | Convert a file to markdown | | `mytool watch <dir>` | Convert on change | ## Options ```text -o, --out <path> output file (default: stdout) -q, --quiet suppress progress output ``` ## Examples Convert and pipe into another tool: ```bash mytool convert report.pdf -q | wc -w ``` ## License MIT
GitHub profile README
The repo named after your username, shown on your profile. Short beats complete — three sections is plenty.
## Hi, I'm Alex 👋 I build developer tools. Currently working on [project](https://github.com/you/project) — markdown sharing for AI workflows. ### Things I've made - [project](https://github.com/you/project) — one-line description - [othertool](https://github.com/you/othertool) — one-line description ### Find me [Blog](https://example.com) · [Bluesky](https://bsky.app/profile/you) · [LinkedIn](https://linkedin.com/in/you) <!-- Optional: GitHub stats card  -->
What makes a good README?
Order sections by reader intent: what is this (one sentence + screenshot), can I use it (install), how do I use it (one real example), then reference material. Badges go under the title and should carry information (version, CI status, license) — not decoration. Keep the quick-start honest: if setup takes six steps, show six steps. And add a table of contents once the file grows past a few screens.
Related
README generator · markdown cheat sheet · images & badges syntax · share a draft for review