How long should a README be?

Long enough to explain the project, installation, and a meaningful first task. Move detailed reference or architecture material to dedicated docs when it makes the quick start hard to find.

Should I include a demo GIF or screenshot?

Include a screenshot or short demo when behavior is visual and the asset can be kept current. Text-only libraries may benefit more from a concise input/output example.

Badges are optional. Add only status indicators readers can interpret and that your automation keeps accurate, such as CI or release status.

Where do I put the license?

Mention it in the README in a short License section, and include a full LICENSE file at the repo root. GitHub auto-detects LICENSE files and displays the type in the sidebar.

Should the README have a table of contents?

Add a table of contents when readers otherwise struggle to scan several major sections. Generate and check it so heading changes do not leave stale links.

How to Write a GitHub README: Examples + Template

A useful README answers three questions quickly: what the project does, how to install it, and how to complete one meaningful task. Put those answers before architecture notes or a long feature catalog.

The examples below are illustrative; replace every package name, command, URL, badge, and output with verified project details. Start faster with the Project README template.

The 10-second rule

When someone lands on your repo, they usually need three answers:

What is this? (One sentence.)
Why should I care? (Why pick this over the 50 alternatives?)
How do I try it? (Copy-paste commands.)

Put those answers near the beginning so readers do not have to hunt for the first working example.

Structure that works

A high-performing README generally follows this order:

Title + logo (optional) + one-line tagline
Badges (optional and relevant)
Demo GIF / screenshot
One-paragraph pitch — what it is, who it's for, why it's different
Quick start — copy-paste install + minimal usage
Features — bulleted, scannable
Usage — common recipes with code
Configuration — options, env vars (or link to docs)
API / CLI reference — or link out
Roadmap (optional)
Contributing — link to CONTRIBUTING.md for anything non-trivial
License
Acknowledgments / inspiration (optional)

Not every project needs every section. A small CLI tool might stop at section 7. A major framework will break sections 8–10 into separate docs.

Section-by-section playbook

Title and tagline

# Acme Widget

> Validate configuration files before deployment.

Title = the project name, nothing else.
Tagline uses a blockquote (>). One line. No marketing jargon. If someone asked "what is this?" at a party, this is what you'd say.

Badges

Good badges communicate health and status:

![npm version](https://img.shields.io/npm/v/@acme/widget)
![build](https://github.com/example/acme-widget/actions/workflows/ci.yml/badge.svg)
![license](https://img.shields.io/github/license/example/acme-widget)

Get badges from shields.io. Put them on one line, after the title, before the description.

Avoid:

A dense row of badges that obscures the project summary
Decorative badges ("made with ❤️", "PRs welcome" without a CONTRIBUTING.md)
Broken badges (dead CI pipelines, outdated numbers)

Demo

For a visual project, choose an asset that demonstrates a real task:

Short recording — for dynamic UIs
Screenshot — for static output
ASCII/terminal cast — asciinema for CLI tools
Hosted live demo link — when you can maintain a safe example

![Demo](./docs/demo.gif)

Compress media and verify that it loads acceptably on the rendered repository page.

The pitch paragraph

Three sentences max:

Acme Widget validates YAML configuration before deployment. It reports the exact
file and line for each invalid value and can run locally or in CI.

This paragraph is the second thing readers look at. Cut words that do not help a reader decide whether the project fits.

Quick start

This is the section that decides whether people actually try your project. Make it copy-paste-able and complete.

## Quick start

```bash
npm install @acme/widget
```

```javascript
import { validate } from "@acme/widget";

const result = validate("service.yml");
console.log(result.ok);
```

The fictional example above should use npm install @acme/widget; replace it with the real, tested installation and usage commands for your project.

Features

Bulleted, scannable, short:

## Features

- Reports invalid keys with file and line context
- Supports local checks and CI validation
- Produces machine-readable output for automation

Emojis are optional but help scanning. Limit to one per line.

Usage recipes

Not every project needs this, but longer projects benefit from 2–4 specific use-case examples:

## Usage

### Convert a file

```bash
acme-widget check service.yml
```

### Watch mode

```bash
acme-widget check config/ --format json
```

Configuration

If your project has options, either include a compact table or link out:

## Configuration

| Option      | Default   | Description                    |
| :---------- | :-------- | :----------------------------- |
| `theme`     | `"light"` | Color theme (`light`/`dark`)   |
| `strict`    | `true`    | Reject unknown keys            |
| `format`    | `"text"`  | Output format (`text`/`json`)  |

See [docs/config.md](./docs/config.md) for the full list.

Contributing

For small projects: a one-liner.

## Contributing

Issues and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

For larger projects, CONTRIBUTING.md covers: dev setup, how to run tests, code style, commit conventions, and the PR process.

License

## License

MIT © [Your Name](https://yourdomain.com)

Standard short form. GitHub picks up the LICENSE file automatically.

Tone guidelines

Write for a tired developer at 4 PM. No one reads your README fresh and alert. Assume distracted.
Second-person, active voice. "Run npm install" > "The user should run npm install."
Skip hype. "Blazing fast", "revolutionary", "game-changing" — readers tune out.
Show, don't tell. "It's easy to use" vs. a 3-line code example. The example wins.

Common README mistakes

1. No install command

If I have to click through to docs, read three pages, and sign up for a mailing list before I can npm install, I'm closing the tab.

2. No demo

An abstract description of a UI tool without a screenshot is basically asking the reader to imagine it. They won't.

3. Too long without a TOC

If readers struggle to navigate a long README, add a TOC with the TOC generator or move deep reference material into a /docs folder.

4. Outdated

A README that shows v0.1.0 when the latest release is v3.4.2 signals abandonment. Automate version badges or schedule quarterly README reviews.

5. Feature list that's just the changelog

"Version 2.3 added X, version 2.4 fixed Y..." — that belongs in CHANGELOG.md, not README.md. The Features section is about what the project does, not its release history.

6. No license

State the project's licensing status and include the appropriate license file. Choose a license with qualified guidance when needed; do not copy one merely because it is common.

Template

Here's a copy-paste starting point. Also available as our Project README template:

# Project Name

> One-line description of what this project does.

![badge1](url) ![badge2](url) ![badge3](url)

![Demo](./demo.gif)

Project Name is a **[what it is]** for **[who it's for]**, designed to **[core value prop]**.

## Quick start

```bash
npm install project-name
```

```javascript
// minimal example
```

## Features

- Feature one
- Feature two
- Feature three

## Usage

### Recipe 1

[code block]

### Recipe 2

[code block]

## Configuration

[table or link to docs]

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT © [Your Name]

Going further

Once your README is solid, the next things to add:

CHANGELOG.md — following keepachangelog.com. We have a Changelog template ready to go.
CONTRIBUTING.md — dev setup, test commands, style guide.
/docs folder — for anything that makes the README too long.
API documentation — see our guide on writing API docs and the API documentation template.

A README is never "done." Revisit it after every major release. The delta between a neglected README and a well-maintained one is often the difference between a dormant project and a thriving one.

Write it once properly. Edit it regularly. Your future contributors will thank you.