How long should a README be?

Long enough to answer three questions: what does this do, how do I install it, and how do I use it. For most projects, 200–800 words is the sweet spot. Move deep reference content (configuration options, architecture) to dedicated docs or a /docs folder.

Should I include a demo GIF or screenshot?

Yes, whenever you can. A 10-second GIF or a single screenshot communicates what your project does faster than any paragraph. Tools like Kap (macOS), ShareX (Windows), and Peek (Linux) make screen recording quick.

Shields (npm version, build status, license, coverage) help signal project health at a glance. Use 3–5 relevant ones, not 15. Skip badges that add noise (e.g., 'made with love').

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?

Only if the README is long (>400 lines or several major sections). Short READMEs don't need one. If you do add a TOC, generate it automatically with our TOC Generator so you don't have to maintain it manually.

How to Write a Great GitHub README (With Template)

A README is the front door of your repository. It's the first thing a visitor sees, the thing that decides whether they star, fork, contribute, or close the tab. And yet most open-source READMEs are either empty, overly terse, or a 5,000-word wall of text.

This guide covers the structure, tone, and specific sections of a README that converts visitors into users and contributors — with a copy-paste template at the end.

The 10-second rule

When someone lands on your repo, they ask three questions in about ten seconds:

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

If your README doesn't answer all three above the fold, you lose most visitors.

Structure that works

A high-performing README generally follows this order:

Title + logo (optional) + one-line tagline
Badges (3–5 max)
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

# mdkit

> The all-in-one Markdown toolkit. Editor, templates, and converters — free and browser-based.

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/mdkit)
![build](https://github.com/you/mdkit/actions/workflows/ci.yml/badge.svg)
![license](https://img.shields.io/github/license/you/mdkit)
![downloads](https://img.shields.io/npm/dm/mdkit)

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

Avoid:

More than 5 badges in the header
Decorative badges ("made with ❤️", "PRs welcome" without a CONTRIBUTING.md)
Broken badges (dead CI pipelines, outdated numbers)

Demo

Nothing sells a project like a 10-second GIF. Some alternatives:

GIF (Kap, ShareX, Peek) — for dynamic UIs
Screenshot — for static output
ASCII/terminal cast — asciinema for CLI tools
Hosted live demo link — the single best "demo" of all

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

Keep GIFs under 5 MB — over that and GitHub may refuse to render inline.

The pitch paragraph

Three sentences max:

mdkit is a free, browser-based Markdown toolkit that combines a real-time editor,
21+ professional templates, and essential converters in one place. It's designed
for developers and writers who want to produce polished documentation without
bouncing between five different tools or uploading sensitive content to cloud services.

This paragraph is the second thing readers look at. Spend an hour on it. Cut every word you can.

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 mdkit
```

```javascript
import { mdkit } from "mdkit";

const html = mdkit.toHtml("# Hello world");
console.log(html);
// <h1>Hello world</h1>
```

Do not say "see the docs for installation." Put the install command right here. Do not link to a getting-started page for the first usage example. Show it inline.

Features

Bulleted, scannable, short:

## Features

- ✨ Zero dependencies, <10kb gzipped
- ⚡ 100% static export — no backend required
- 🔒 Runs entirely in the browser
- 🎨 Themeable with CSS variables
- 📱 Mobile-first responsive design

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
mdkit convert README.md --to html > README.html
```

### Watch mode

```bash
mdkit watch docs/ --out build/
```

Configuration

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

## Configuration

| Option      | Default   | Description                    |
| :---------- | :-------- | :----------------------------- |
| `theme`     | `"light"` | Color theme (`light`/`dark`)   |
| `gfm`       | `true`    | GitHub Flavored Markdown       |
| `breaks`    | `false`   | Render `\n` as `<br>`          |

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

READMEs over 400 lines without navigation are punishing. Either add a TOC (auto-generate it with our TOC generator) or split into multiple files in 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

No license = no legal permission to use it. Always include one. If you genuinely don't care, MIT is the lowest-friction default.

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.