How to Write a Good README (with an Example and a Free Generator)

A README is the first thing people see when they open your project. It has to answer three questions quickly: what is this, how do I start, and can I use it? If it doesn’t, most visitors leave, however good the code is. And six months from now, the person reading it may be you.

This guide shows what belongs in a good README, in what order, with a complete example. If you’d rather not start from a blank page, the free README Generator writes it from a short form.

What is a README file?

It’s a text file in the top folder of a project, usually called README.md. The .md means it’s written in Markdown, a simple way to format text. GitHub, GitLab and similar sites show it automatically on the project’s front page, which makes it your project’s home page.

What to put in a README, in order

1. Name and one-line description. Say what it does, not how it’s built. “Save your favourite recipes and find them again in seconds” beats “A React and Node.js application”.
2. Badges (optional). Small labels showing the license, the current version or the number of stars.
3. Table of contents. Worth having once a README is longer than one screen.
4. About. Two or three sentences: what problem it solves and who it’s for.
5. Features. A short list, so people can see at a glance whether it does what they need.
6. Installation. The exact commands, ready to copy. Try them yourself on a clean machine: missing steps are the most common README problem.
7. Usage. The smallest example that works. A short code sample tells people more than a long explanation.
8. Screenshot. For anything with a screen, one picture saves a paragraph.
9. Contributing. How others can help, such as opening an issue before sending a change.
10. License and author. What people may do with your work, and who made it.

A small project doesn’t need all of these. Name, description, installation, usage and license are the core.

A complete README example

Here’s a short README for a small project, ready to adapt:

# recipe-box

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Save your favourite recipes and find them again in seconds.

## Table of contents

- [About](#about)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [License](#license)

## About

A small app for people with too many recipes in too many places.
Everything is stored on your own computer.

## Features

- Search by ingredient
- Works offline
- Export to PDF

## Installation

```bash
git clone https://github.com/janedoe/recipe-box.git
cd recipe-box
npm install
```

## Usage

Start the app and open http://localhost:3000:

```bash
npm start
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

© 2026 Jane Doe

How to make one with the generator

1. Open the README Generator. Click Sample to see a filled-in example, or Clear to start with your own.
2. Fill in the Project name and the One-line description. Add the GitHub repository as owner/name and the npm package if you have them: the badges and links use them.
3. Fill in the sections you want, such as Features (one per line), Installation and Usage. Sections you leave empty are left out.
4. Tick or untick Badges and Table of contents, and choose a License.
5. Check the result under Preview, or see the code under Markdown, then click Copy or Download. A downloaded file has a dated name, so rename it to README.md.

You can write the README in English, Spanish, German or French: README language sets the headings and standard sentences, and what you type stays as you wrote it. Badges appear as labelled boxes in the preview, because it doesn’t load pictures from other sites; on GitHub they show normally.

Which license should I choose?

Without a license, others have no clear right to use your code, even if it’s public. These are the options in the generator, in brief. This is general information, not legal advice.

• MIT and ISC: short and permissive. People can do almost anything as long as they keep your copyright notice.
• Apache-2.0: also permissive, with an explicit patent grant.
• BSD-3-Clause: permissive, and others may not use your name to promote their products without permission.
• MPL-2.0: changes to your files must be shared, but those files can be part of a larger closed project.
• GPL-3.0: anything distributed that’s based on your code must also be open source under the GPL.

One step the README doesn’t do for you: the License section only points to the license. Add the full text as a file named LICENSE too. On GitHub, choose Add file, type LICENSE as the name and pick a template.

Common README mistakes

• Starting with the technology. Say what it does for the reader first.
• Commands that don’t work. Run them yourself, and update them when the project changes.
• Assuming knowledge. Mention what must be installed first, such as Node.js or Python, and which version.
• A wall of text. Use headings, short lists and code blocks.

More Markdown tools

• Markdown Table Generator: build tables for your README in a grid, or paste them from Excel.
• Markdown to HTML: turn your README into a web page. See also how to convert Markdown to HTML.

Frequently asked questions

Does it have to be called README.md?

Yes, if you want GitHub and similar sites to show it automatically. Put it in the top folder of the project.

Is what I type uploaded?

No. The README is made in your browser, so what you type never leaves your device. Filling in the form is free; copying or downloading the result counts as one use of your daily allowance.

Can I change the README later?

Yes. It’s a plain text file: edit it in any text editor, or directly on GitHub. Update it whenever installation or usage changes.