A README is the file readers see first when they land on your project. The tool above generates README scaffolds with the standard sections; you fill in the content. The output is Markdown, which renders on GitHub, GitLab, npm, PyPI, and most other places code lives.

The five sections that always matter

# Project Name

[1-2 sentence elevator pitch.]

## Installation

npm install your-package

or

pip install your-package


## Usage

```javascript
const x = require('your-package');
x.doSomething();

Documentation

[Link to docs site or expand here for small projects.]

License

MIT


These five answer the questions a reader has when they arrive: what is this, how do I get it, how do I use it, where's more info, what are the rights.

For very small projects, this is enough. For larger projects, you add sections.

## The optional sections, in priority order

| Section | When to include |
|---|---|
| **Badges** | Almost always — build status, npm version, license. Ranks signals at a glance. |
| **Demo / screenshot** | If the project produces visual output. |
| **Features** | Bulleted list of capabilities, especially if the elevator pitch can't carry it. |
| **Quick start** | If usage examples are nontrivial. Often combined with "Usage." |
| **API reference** | For libraries, especially if no separate docs site exists. |
| **Configuration** | If the project has many options. |
| **Contributing** | When you want PRs. Often a separate `CONTRIBUTING.md` linked from here. |
| **Changelog** | Better as a separate `CHANGELOG.md`; link from here. |
| **Related projects** | Useful when your project sits in a constellation. |
| **Acknowledgments** | If specific people or projects materially contributed. |

The order in the README typically reads: pitch → screenshot/badges → install → usage → API → contributing → license. That's roughly the order of decreasing reader-priority.

## Badges

The little colored rectangles at the top of many READMEs:

```markdown
[![npm version](https://img.shields.io/npm/v/your-package.svg)](https://www.npmjs.com/package/your-package)
[![Build Status](https://github.com/you/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/you/repo/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Useful badges:

Package version (npm, PyPI, crates.io). Tells readers if the package is active.
Build status / CI (GitHub Actions, etc.). Signals project health.
License. Linked badge to license terms.
Code coverage. If you have it set up.
Downloads / stars. Signals popularity (some find these tacky; they’re not load-bearing).

The dominant badge service is Shields.io. Don’t go overboard — five badges is plenty; ten is too many.

Code blocks with language hints

Always specify the language in fenced code blocks:

```javascript
const x = require('your-package');
```

```bash
$ your-cli --help
```

```python
import your_package
```

The language hint enables syntax highlighting on rendered platforms. Without it, the code is monochrome. See markdown cheat sheet for the broader syntax reference.

What to put in the elevator pitch

The first 1-2 sentences after the project name are read by every visitor. They should answer:

What does this thing do?
Why would someone use it?

Bad: “A modern, lightweight, fast, easy-to-use library for X.” (Empty adjectives.) Better: “Convert CSV files to JSON in the browser without uploading them. Handles RFC 4180 quoting and 100MB+ files.”

Specifics over adjectives. The reader can decide whether “modern” matters; they can’t decide whether your CSV-to-JSON tool actually does what they need without specifics.

License section

Every README should declare a license. The options:

MIT — permissive, widely used, recognized.
Apache 2.0 — permissive plus explicit patent grant.
BSD-3-Clause — permissive, similar to MIT.
GPL/AGPL — copyleft, source must remain open in derivatives.
Unlicense / CC0 — public domain dedication.
Proprietary — not open source; specify usage terms.

If you don’t pick a license, the default in most jurisdictions is “all rights reserved” — meaning others legally can’t use, modify, or distribute your code. For an open-source project, always pick a license.

The README section is just a pointer; the actual license terms go in a LICENSE file at the repo root.

What not to put in the README

Wall of features without examples. Show, don’t list.
API reference for a 200-method library. Link to docs; don’t paste them.
Old changelog history. Link to CHANGELOG.md; don’t bloat the README.
Marketing copy. “Revolutionary,” “game-changing.” Skip.
The author’s life story. A two-line bio is fine; a paragraph is too much.
Setup tasks the user shouldn’t have to do. If you can ship a sane default, do; don’t make the README explain the workaround.

What the tool above generates

The tool produces a README scaffold from a short form (project name, tagline, description, GitHub URL, install command, usage example, license). It includes:

A title, tagline and description.
Optional shields.io badges (license, npm version, build status, GitHub stars) built from the GitHub URL.
An installation block with the command you enter.
A usage code block with the language hint you choose.
A license section.
Optional table of contents, Features, Configuration and Contributing sections (placeholder text for you to replace).

Edit the scaffold to fill in real content. The scaffold is a starting point; the value of a README is in the writing, not the structure.

Common pitfalls

No README. First impression: the project is unfinished or undocumented. A bad README is better than no README.
README is the last thing written. By then, you’ve lost the new-user perspective. Write or revise the README earlier in the project — even before the code is feature-complete.
Outdated installation instructions. Package name changed; required Node version moved; install command no longer works. Re-test the install instructions periodically.
No usage example. Reader has to guess. Always include at least one runnable example.
All examples in one language. A polyglot project should show usage in each supported language.
Broken links. Especially to docs sites that have been restructured. Link checker in CI catches these.

For other documentation generators, see meta tag generator, Open Graph generator.

README Generator