Generate a project README

How to use the README Generator

1. Enter the project name, a one-paragraph description and the repository URL.
2. Pick the ecosystem so the install and run commands are right.
3. List the features and paste a usage snippet.
4. Generate, then save the Markdown as README.md in the repository root.

What a README has to do in the first screen

Most readers decide within a few seconds whether your project is the one they want. Everything that decision needs has to be above the fold: the name, one sentence saying what it does and for whom, and how to install it. Feature lists, architecture diagrams, sponsor blocks and long badge rows all push that decision further down the page.

A good order — and the one this generator produces — is: name, badges, one-paragraph description, features, requirements, installation, usage, configuration, contributing, licence. It matches how people scan: is this the right thing → can I run it → how do I use it → may I use it.

Where the file is read

GitHub renders README.md from the repository root, and also picks it up from docs/ or .github/. npm shows it on the package page, pkg.go.dev renders it for Go modules, PyPI uses whatever your project metadata points at, and crates.io shows it for Rust crates. One well-written file therefore does duty in several places, which is a good argument for keeping links relative to the repository so they still resolve on a fork.

Badges

The badges here come from shields.io, which builds an SVG from a URL. Licence and build status earn their place because they answer real questions. A wall of twenty badges does not: it pushes your description below the fold and signals that nobody has edited the file recently. Three is usually plenty.

A README is not a licence

Writing "MIT licensed" in a README is a statement of intent, not a grant. Under the Berne Convention, creative work is protected by copyright the moment it is written, and with no licence file, the default is exclusive copyright: nobody may legally copy, modify or redistribute your code, however public the repository is. Add the full licence text in a LICENSE file at the root, and set the matching SPDX identifier in your package metadata — license in package.json, license in pyproject.toml, license in Cargo.toml — so tooling, scanners and corporate policy checks can read it without parsing prose.

Writing the usage section

The single most valuable thing in a README is the smallest example that does something real, in a fenced code block with the language named so it is highlighted. Test it by pasting it into a clean shell or file. The classic failure is an example that works only on the author’s machine, against a config file the reader has never seen, using a variable defined somewhere off-screen.

Two more habits that save everyone time: state the minimum version you actually test against rather than the newest one you happen to have installed, and show output as well as input, so a reader can tell whether their run went right.

Markdown that GitHub understands

GitHub Flavoured Markdown adds tables, task lists, strikethrough, automatic links and fenced code blocks to CommonMark. It also supports alert blocks — a blockquote beginning [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] — which render as coloured callouts. Headings automatically get anchors derived from their text, so ## Getting started can be linked as #getting-started; add a table of contents only when the file is long enough that someone would actually use it.

Privacy

This tool runs entirely inside your browser using WebAssembly and the Canvas/File APIs. Your files are never uploaded to ToolFlint or any third party; you can verify this in your browser's network tab or by switching to airplane mode after the page loads. Read how we process files.

Last updated 2026-09-23.