GitHub README Template — How to Write a Great README

Your README is the front page of your project. It is the first thing people see on GitHub, and in a few seconds it has to answer three questions: What is this? Why should I care? How do I use it? A clear README gets more stars, more contributors and fewer “how do I install this?” issues. Below you will find a free template you can copy, an explanation of each section and tips for making your README stand out.

What makes a good README

• Clarity first. A one-sentence description of what the project does and who it is for.
• Fast start. Installation and a minimal usage example within the first screen.
• Visual proof. A screenshot, GIF or diagram showing the project in action.
• Scannable structure. Short sections with clear headings — GitHub automatically builds a table of contents from them.
• Honest status. Badges or a note on whether the project is stable, in beta or unmaintained.

The template

Copy this into README.md in the root of your repository and replace the placeholders:

# Project Name

> One sentence that explains what the project does and who it is for.

![License](https://img.shields.io/github/license/USER/REPO)
![Stars](https://img.shields.io/github/stars/USER/REPO)
![Last commit](https://img.shields.io/github/last-commit/USER/REPO)

![Screenshot](docs/screenshot.png)

## Features

- ⚡ Feature one — short benefit
- 🔒 Feature two — short benefit
- 🧩 Feature three — short benefit

## Installation

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

## Usage

```javascript
import { doSomething } from "project-name";

doSomething({ option: true });
```

## Configuration

| Option   | Type    | Default | Description          |
|----------|---------|---------|----------------------|
| `option` | boolean | `false` | What this option does |

## Roadmap

- [x] Initial release
- [ ] Plugin system
- [ ] Documentation site

## Contributing

Contributions are welcome! Please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create a branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -m "Add my feature"`
4. Push and open a pull request

## License

[MIT](LICENSE) © Your Name

Section by section

Title and description

Use a single H1 with the project name, followed by a one-line description. Avoid jargon — someone who has never heard of your project should understand it.

Badges

Badges from shields.io show license, version, build status, downloads or coverage at a glance. Three to five are plenty; a wall of badges is noise.

Screenshot or demo

A picture beats a paragraph. Store images in the repo (for example docs/screenshot.png) and reference them with a relative path so they work in forks and on GitHub Pages. Always write meaningful alt text.

Installation

Give the exact commands to copy. If there are prerequisites (Node 20+, Python 3.11+, Docker), list them first.

Usage

The smallest example that does something useful. Link to full documentation for everything else.

Configuration

A table is the clearest way to document options. Build one quickly with the Markdown Table Generator or convert an existing config with the JSON to Markdown converter.

Contributing and license

Say whether you accept contributions and how. Always state the license — without one, others legally cannot reuse your code. For a longer guide, add a CONTRIBUTING.md file.

GitHub-specific features worth using

Alerts highlight important notes:

> [!NOTE]
> Requires Node.js 20 or later.

> [!WARNING]
> Version 2 contains breaking changes.

Other types are [!TIP], [!IMPORTANT] and [!CAUTION].

Collapsible sections keep long content out of the way:

<details>
<summary>Advanced configuration</summary>

Detailed options go here.

</details>

Diagrams with Mermaid render directly in the README. Draft them in the Mermaid editor, then paste the code block:

```mermaid
flowchart LR
    Client --> API --> Database
```

Task lists (- [ ]) make a lightweight roadmap — see our guide to Markdown checkboxes.

Light and dark mode images — GitHub supports the <picture> element, so you can show a different logo for each theme.

README checklist

• Clear name and one-sentence description
• Screenshot, GIF or diagram
• Installation commands that work when copied
• Minimal usage example
• Configuration options documented
• License stated
• Links checked and images use relative paths
• Spelling checked

What to emphasize for different projects

Common README mistakes

• No description at the top. Visitors should not have to read the code to learn what the project does.
• Outdated install steps. Re-run your own instructions on a clean machine after major changes.
• Absolute links to images on your branch. Use relative paths like docs/demo.gif so links keep working.
• A wall of text. Break content into short sections with headings, lists and code blocks.
• Missing license. Without one, people and companies cannot legally use your code.
• Badges that are always red. A failing build badge is worse than no badge — fix it or remove it.

Keep it up to date

Treat the README like code: update it in the same pull request that changes behavior, and review it before each release. A short “Last updated” note or a link to the changelog tells visitors that the project is alive.

Frequently asked questions

Where should the README file go?

In the root of the repository, named README.md. GitHub also recognizes a README in .github/ or docs/. A special repository named after your username (username/username) shows its README on your GitHub profile.

How long should a README be?

Long enough to get someone from zero to a working example. Move detailed reference material to a docs folder or site and link to it.

How do I preview my README before pushing?

Paste it into the Markdown editor or open it with the Markdown viewer to see the rendered result. Keep in mind that GitHub-only features such as alerts may look different outside GitHub.