README Generator

Why READMEs get abandoned half-written

You finish the project, flip the repo to public, open README.md, write the title and a one-line description, and then stop. What stalls the file is almost never the prose. It is the decision: does this need a Roadmap section, a screenshot, a badge row? While that stays unresolved the file grows an empty "## Usage" heading and sits there for a year.

The form below makes that decision by omission. Leave a field blank and its section is never emitted: no features means no Features heading, no requirements means no Requirements heading. What you end up with is short but complete, rather than a scaffold of placeholders that signals nobody is home.

What a README owes a first-time visitor

Someone landing on your repository is answering three questions: what does this do, will it work for me, how do I install it. All three belong above the fold. Project name, a one-line tagline, a short description, then installation. Architecture notes, design rationale and benchmark tables move down the page or out of the file entirely.

The most commonly dropped line in an install block is the clone itself. The maintainer is already inside the directory, so they write npm install and move on, forgetting that the reader has not downloaded anything yet. Fill in the repo field and the generator emits all three lines together:

1git clone https://github.com/owner/project.git2cd project3npm install

That block works when selected and pasted whole. Switch the package manager to yarn, pnpm or bun and the install command changes with it. Supply your own command and it replaces the default rather than sitting next to it.

Badge fatigue

Badges are useful right up to the point where there are fifteen of them and none get read. The generator emits four, all derived from the repo path: licence, stars, open issues, last commit. Every one speaks to whether the project is alive, which is what a visitor is trying to work out before investing an afternoon in it.

A README is not documentation

A README is a pitch plus a quick start. Documentation is reference material: every function signature, every configuration key, every error code. Compress both into one file and you get 900 lines that serve neither purpose. The practical test is scroll depth. If a README does not end within a few screens, the surplus belongs in a docs/ directory or a wiki.

Table of contents and anchor matching

GitHub derives an anchor from every Markdown heading: lowercase it, drop punctuation, replace spaces with hyphens. The detail that catches people out is that letters outside ASCII are kept as they are rather than transliterated. A heading of ## Kurulum ve Çalıştırma produces #kurulum-ve-çalıştırma, not #kurulum-ve-calistirma. Anyone hand-writing a contents list tends to simplify those characters, and the links then silently jump nowhere.

1## Table of Contents2 3- [Kurulum ve Çalıştırma](#kurulum-ve-calistirma)   <!-- dead link -->4- [Kurulum ve Çalıştırma](#kurulum-ve-çalıştırma)   <!-- correct -->5 6## Kurulum ve Çalıştırma

Because the generator derives the contents list from the same headings it emits, the two cannot drift apart. There is also a threshold: with two sections or fewer the list is skipped entirely, since a three-item table of contents only adds height to a page nobody needed help navigating.