README Template for GitHub Projects — Copy, Paste, Ship

Every project needs a README. Most developers either write too little (“TODO: add docs”) or too much (a 2,000-word essay nobody reads). Here's a template that hits the sweet spot.

The template

This structure works for libraries, CLIs, web apps, and APIs. Skip sections that don't apply — an empty section is worse than a missing one.

# Project Name One-line description of what this project does and who it's for. ![Demo](screenshot.png) ## Features - **Feature one** — brief description - **Feature two** — brief description - **Feature three** — brief description ## Quick Start ```bash npm install your-package ``` ```javascript import { thing } from 'your-package' const result = thing.doSomething() console.log(result) ``` ## Installation ### Prerequisites - Node.js 18+ - npm or yarn ### Setup ```bash git clone https://github.com/user/repo.git cd repo npm install cp .env.example .env.local npm run dev ``` ## Usage ### Basic usage ```javascript // Most common use case ``` ### Advanced usage ```javascript // Configuration options, edge cases ``` ## API Reference | Parameter | Type | Default | Description | |-----------|----------|---------|----------------------| | `option1` | `string` | `""` | Description of opt 1 | | `option2` | `number` | `10` | Description of opt 2 | ## Environment Variables | Variable | Required | Description | |-----------------|----------|------------------------| | `DATABASE_URL` | Yes | PostgreSQL connection | | `API_KEY` | Yes | Your API key | ## Contributing Contributions welcome. Please read CONTRIBUTING.md first. 1. Fork the repo 2. Create a feature branch 3. Commit your changes 4. Open a PR ## Licence MIT — see [LICENCE](LICENCE) for details.

Why this structure works

Description first, tech second

Lead with the problem you solve, not the stack you used. “Real-time collaborative markdown editor” tells me what I can do. “React + Socket.io + MongoDB app” tells me nothing useful.

Quick start before full installation

Power users want to try your tool in 30 seconds. Give them a quick start — then provide detailed installation for people who need it.

Examples over explanations

Every usage section should have runnable code. Developers learn by example, not by reading paragraphs. If your code examples aren't copy-pasteable, rewrite them.

Tables for reference data

API parameters, environment variables, and configuration options belong in tables. They're scannable and dense — exactly what reference docs need.

Sections to skip

  • “About the project” — Your description already covers this. Don't repeat yourself.
  • “Built with” — A tech stack list adds no value to users. They can see your package.json.
  • “Acknowledgements” — Unless someone made a major contribution, skip it. Put it in CONTRIBUTORS.md if needed.
  • “Roadmap” — Use GitHub Issues or a ROADMAP.md. Roadmaps in READMEs go stale instantly.

Skip the template — generate it

README Writer analyses your actual repo and generates a tailored README with the right sections, features, and setup instructions.

Generate README →