README Generator
Scaffold a project README from a small form.
Overview
Fill in project name, description, install instructions, usage example, and a license, and the generator emits a structured README skeleton with the standard sections - Overview, Installation, Usage, Development, Contributing, License. The output is opinionated but predictable, so contributors find what they're looking for.
It's for maintainers bootstrapping a new project or refreshing a README that's grown stale. Reach for it when scaffolding a repo, polishing an open source project before announcing it, or producing a baseline that a team can iterate on.
How it works
The generator uses a Markdown template that mirrors the structure recommended by the OSS Guides and most popular GitHub READMEs - a short hero block (badges, one-line description), installation, usage, optional API/screenshots section, contributing, and license. Headings are deterministic so navigation links are predictable.
Badge URLs are filled in for the common services (GitHub Actions, npm, PyPI, Codecov, license) using the project name to construct shields.io image URLs - no API calls, just templated URLs that work once the project is published.
Examples
- Top of the file:
# my-project > A short tagline. ## Installation ```bash npm install my-project - Usage block:
## Usage ```js import { thing } from 'my-project'; thing(); - Standard footer sections:
## Contributing PRs welcome. See CONTRIBUTING.md. ## License MIT - Badge row near the top:
[](https://github.com/me/proj/actions)
FAQ
Should I keep the README short?
A README is the first impression - keep the top of the file fast to skim (1-2 paragraphs) and push details to dedicated docs files. Aim for under 500 lines total.
What goes in ## Usage vs ## API?
Usage shows the most common workflow as a working example. API documents every public function and option - link to it from Usage, or split into a docs/ folder if it grows.
Do I need a CONTRIBUTING.md?
For anything you want PRs against, yes. Even a 20-line file outlining how to install, test, and submit a PR cuts back-and-forth dramatically.
Should I commit screenshots?
Yes for visual tools - even one screenshot helps a casual reader gauge what your project does. Keep them small and host inside the repo.