How to Write a Great README (Template Included)

Your README is the front page of your project. Most visitors decide in under a minute whether to keep reading, so a good README answers their questions in the order they ask them. Here is what to include, why, and a template you can start from.

1. Name and one-line description

Start with the project name as a level-one heading, followed by a single sentence that says what it does. Not what it is — what it does.

Weak: “A TypeScript library.”

Strong: “Converts Markdown to Word documents in the browser.”

2. Badges (optional, but useful)

A small row of badges signals that a project is maintained: build status, latest version, license, and download count are the common ones. Keep it to four or five. The badge generator builds correct shields.io URLs for GitHub and npm so you do not have to.

3. A screenshot or demo

If your project has any visual output, show it. One screenshot or a short GIF does more than three paragraphs of description.

4. Installation

Give the exact command. Put it in a fenced code block with a language so it is highlighted and easy to copy:

npm install your-package

If there are prerequisites — a minimum Node version, a system library — list them before the command, not after the reader has already hit an error.

5. Usage

Show the smallest example that does something useful. Readers copy and paste this, so make sure it runs as written.

import convert from 'your-package';

const docx = await convert('# Hello');

Then link to fuller documentation rather than putting every option in the README.

6. Contributing

Explain how to report bugs and propose changes. Even one sentence — “Open an issue to discuss before sending a large pull request” — saves maintainers and contributors time.

7. License

State the license and link to the full text in a LICENSE file. Without a license, others legally cannot reuse your code, however public the repository is.

Common mistakes

• Out-of-date install steps. Re-run them in a clean environment before each release.
• No table of contents in a long README. If your README scrolls for more than two screens, add one. The TOC generator creates GitHub-compatible anchor links.
• Walls of text. Use headings, short paragraphs, and lists.
• Broken Markdown. Run it through the Markdown formatter to catch skipped heading levels and inconsistent lists.

The template

# project-name

> One sentence describing what the project does.

![Build](https://img.shields.io/github/actions/workflow/status/owner/repo/ci.yml)
![License](https://img.shields.io/github/license/owner/repo)

## Installation

    npm install project-name

## Usage

    import project from 'project-name';
    project.run();

## Contributing

Pull requests are welcome. Please open an issue first to discuss major changes.

## License

[MIT](LICENSE)

Or skip the typing: the README generator builds all of this from a short form, with a live preview, and the templates gallery has a README you can open in the editor in one click.