How to use the README Generator
- Pick the project type — library, app / website or Webflow site — or load one of the examples to see a finished README.
- Fill in the name, tagline and description. Add your GitHub repo and package name to get install commands and badges automatically.
- Add features, a usage example, configuration options, environment variables and a roadmap — empty sections are simply left out.
- Check the live preview and the completeness checklist, then Copy or Download README.md and commit it to the root of your repository.
What makes a good README?
A README is the front page of a project. On GitHub, npm and PyPI it’s the first — and often the only — thing people read before deciding to use, hire or contribute. The best READMEs answer five questions in this order: what is it, why should I care, how do I install it, how do I use it and under which license. Everything else (configuration, roadmap, contributing) supports those answers.
The structure this generator uses
| Section | Why it’s there |
|---|---|
| Title + badges | Name, version, build status and license at a glance (badges via shields.io). |
| Tagline | One sentence that explains the project — also used by GitHub and search snippets. |
| Screenshot | For apps and UI libraries, a picture is the fastest explanation. |
| Features | Scannable bullets that help people decide in seconds. |
| Installation | Exact, copy-pasteable commands for your package manager, plus .env variables. |
| Usage | The smallest working example. This is the most-read part of any README. |
| Configuration | Options as a table with type, default and description. |
| Roadmap, Contributing, License | What’s next, how to help and how the code may be used. |
README for Webflow projects and client handoffs
Webflow sites don’t live in a Git repository, but agencies still need documentation when a site changes hands. The Webflow site preset produces a handoff README: CMS collections, integrations, where custom code lives (Site settings vs page settings), naming system (for example Client-First) and the tech stack. Keep it in your project folder or paste it into a Notion page. Pair it with the Class Name Typo Checker before the handoff, and add an llms.txt so AI assistants understand the site too.
Writing tips
- Lead with the outcome, not the technology: “Turn any string into a URL-safe slug” beats “A TypeScript utility using Unicode normalization”.
- Make examples copy-pasteable and runnable — no placeholders that break when pasted.
- Use relative links for files in the repo (
./docs/setup.md,LICENSE) so they work on forks and branches. - Keep it current: an outdated install command does more harm than a short README.
- Long reference docs belong in a
/docsfolder; link to them from the README.
Choosing a license
Without a license, code is “all rights reserved” by default — others can read it but not legally reuse it. MIT and ISC are short and permissive, Apache 2.0 adds an explicit patent grant, and GPL v3 requires derivatives to stay open source. For client or company work, choose Proprietary. This isn’t legal advice; check choosealicense.com for details. Remember to add the matching LICENSE file too.
Need to tidy up text first? The Markdown to HTML converter, Markdown Task List Converter and JSON to Markdown Table tool all produce GitHub-flavored Markdown that you can paste into the README.
Tools that pair well with the README Generator
- humans.txt Generator — Create a humans.txt that credits the team, contributors and technology behind your website.
- HTML Formatter — Paste minified or messy markup and get clean, consistently indented HTML — including embedded <style> and <script> blocks.
- CSS Formatter — Turn a minified stylesheet into readable CSS with one property per line and properly nested @media blocks.
- JavaScript Formatter — Unminify and pretty-print JavaScript, JSON or JSX with your preferred indentation and brace style — or strip whitespace and comments with a verified minifier.
Frequently asked questions
Where do I put the README.md file?
README.md on the project page.