{{ summaryTitle }}
{{ summaryPrimary }}
{{ summaryLine }}
{{ badge.label }}
Use the closest project type; it changes section names and audit expectations.
Use the exact name readers will search for or install.
Write one clear paragraph readers can understand before setup.
Optional but recommended for copy-ready install and contribution links.
List the capabilities that tell readers whether the project fits their need.
One prerequisite per line; leave blank only when there are no special requirements.
Include clone, install, migration, or setup steps needed before first run.
Make this the fastest successful path after installation.
Use an SPDX-style label when the repository is open source.
Keep it short, for example Blue Oak Model License 1.0.0.
Active omits the status note; other states add a clear status callout.
Open-source projects should point to contribution and code-of-conduct files when available.
Link to full guides, API docs, or team docs if they exist.
Leave blank if tests are not ready to document.
One short note per line; generated as bullets.
Generated as a Markdown table when at least one variable is present.
Add one concise line per endpoint, option, artifact, or operating note.
Optional, but the audit will flag missing help routes for public projects.
Use a relative path such as CONTRIBUTING.md or docs/CONTRIBUTING.md.
Leave blank when the project is not accepting contributions.
Optional for small projects, recommended for published software.
Leave blank unless users need formal citation guidance.
Leave off for short READMEs; turn on for longer generated drafts.
{{ include_toc ? 'On' : 'Off' }}
Optional badges stay near the top and never replace setup instructions.
{{ include_badges ? 'On' : 'Off' }} 
{{ markdownOutput }}
Area Status Signal Next copy Copy
{{ row.area }} {{ row.status }} {{ row.signal }} {{ row.nextCopy }}
Repository item Status Why it matters Next action Copy
{{ row.item }} {{ row.status }} {{ row.reason }} {{ row.nextAction }}
Tags: Devtools, Productivity
Export to PDF Fullscreen
Customize
Advanced
:

A README is the front door for a software repository. It tells a first-time reader what the project does, why it exists, how to install or run it, where to get help, and what rules apply before someone depends on the code.

Project facts flowing into a README draft, section audit, and repository checklist

Good README writing is practical information architecture. The opening paragraph sets the reader's expectation, setup commands prove the project can be tried, usage examples show the first successful run, and support details tell readers what to do when the happy path fails.

A generated draft still needs review by someone who knows the repository. The text can organize known facts, but it cannot confirm that commands still work, that a license is legally appropriate, or that contribution and security files already exist.

Technical Details:

README generation is a structured text assembly task. Project facts become Markdown sections, while review rules check whether the draft has enough information to help a reader install, run, test, cite, support, or contribute to the repository.

The profile choice changes the emphasis without changing the basic README shape. A CLI tool needs options, a web app or API needs endpoint notes, a data or research project needs reproducibility and citation cues, and an internal service needs operations notes.

Transformation Core:

Input group Generated Markdown behavior Result surface to review
Project name and short description The project name becomes the top heading, and the description becomes the first paragraph before generated sections. README Draft should open with the exact public project name and a clear purpose statement.
README profile The profile maps custom notes to API Reference, Options, API, Data and Reproducibility, or Operations. The section title should match how readers will use the repository.
Requirements, install commands, usage example, and test command Requirements become bullets, while command fields become fenced shell blocks for setup, usage, and testing. Section Audit flags missing setup and usage as blocking gaps.
Configuration notes and environment variables Configuration notes become bullets. Environment variable lines such as PORT=HTTP port become a Markdown table. README Draft should show variable names and descriptions without losing defaults or required values.
Contribution posture and support paths Open-source mode adds contribution guidance, internal mode routes changes to the owning team, and closed mode omits contribution invitations. Repository Checklist reports whether contribution, conduct, support, and security paths are linked or recommended.
License, citation, documentation, table of contents, and badges These fields add license text, citation DOI, documentation link, optional heading links, and conservative badge Markdown when supported by the repository URL. JSON records settings, metrics, warnings, section names, audit rows, checklist rows, and the generated Markdown.

Audit Rules:

Status Meaning Typical correction
Ready The entered value satisfies the local rule for that README area. Keep the value, then verify it against the repository before publishing.
Check A value exists, but it may be too short, vague, incomplete, or risky for readers. Use the row's Next copy guidance to add missing detail.
Missing A required README area has no usable value, such as setup commands or a usage example. Fill the named input before copying the draft.
Optional The area may be useful, but the local rules do not require it for every repository. Add it when the project needs docs, a support route, citation, or repository health files.

Everyday Use & Decision Guide:

Begin with the closest README profile, then fill Project name, Short description, Install or setup commands, and Usage example. Those fields carry the first reader decision: whether the repository is relevant and whether the first run is realistic.

Use the advanced fields when the README must do more than quick-start. Project status adds a clear note for beta, maintenance, deprecated, or internal projects. Contribution posture changes whether the draft invites pull requests, routes internal changes, or avoids contribution copy.

  • Set Include quality badges only when the repository URL points to a GitHub-style project and the badge path matches a real CI workflow.
  • Add Support contact for public projects before copying the draft; readers should not have to infer where bug reports belong.
  • Use Environment variables for names and defaults that affect first run, not for every internal setting.
  • Keep Configuration notes short enough that the README stays a starting point and longer guides can live behind Documentation URL.
  • Use Citation DOI only when the project should be cited as research software, a dataset, or a release artifact.

The draft is a good fit for scaffolding a repository README, checking whether the usual sections are present, and handing a maintainer a copy-ready first pass. It is not a repository scanner, license chooser, CI validator, or legal review.

Treat README notes and Section Audit as review blockers when they mention missing setup, missing usage, a short opening description, incomplete community files, or badge links that need a GitHub repository URL.

Step-by-Step Guide:

Build the draft from reader-critical facts first, then use the audit and checklist to decide what still needs repository review.

  1. Choose README profile. Confirm the summary badge changes to Library/package, CLI tool, Web app/API, Data/research, or Internal service.
  2. Enter Project name and Short description. The README Draft should update its heading and opening paragraph immediately.
  3. Fill Key features, Requirements, Install or setup commands, and Usage example. If README notes reports missing setup or usage, add the missing field before copying Markdown.
  4. Choose License and add a custom label only when the selected license control is set to Custom license label. Check that the generated License section matches the intended reuse terms.
  5. Open Advanced for project status, contribution posture, docs, tests, configuration, environment variables, support, contribution guide, code of conduct, security policy, citation, table of contents, and badges.
  6. Review Section Audit. Copy a row when its Next copy guidance needs to be handed to a maintainer or issue comment.
  7. Open Repository Checklist and JSON before exporting. The checklist should agree with the paths and posture you entered, and the JSON should reflect the same readiness percentage and warnings shown in the summary.

Interpreting Results:

README draft ready means the entered values cleared the local checks without review notes. The readiness percentage is a drafting signal, not proof that the repository is complete or that every command has been tested.

README draft needs review means at least one warning is present. Missing setup and usage warnings usually matter most because they stop a reader from reaching the first successful run.

  • Section Audit is strongest for content gaps: short description, missing features, missing install commands, missing usage, unclear support, and incomplete community links.
  • Repository Checklist is strongest for follow-up files: LICENSE, contribution guide, code of conduct, security policy, changelog, docs, CI workflow, and citation file.
  • JSON is useful when the README draft, warnings, metrics, audit rows, and checklist rows need to be archived or passed to another workflow.

Worked Examples:

Small web service. A project named signal-exporter with the Web app/API profile, Node.js requirements, setup commands, a curl health-check usage example, and GET /health in profile notes should produce a README with Installation, Configuration, Usage, API, Testing, Support, Contributing, Security, and License sections. Section Audit should mark setup and usage as Ready.

Internal maintenance service. Choosing Internal service, Maintenance only, and Internal team should add a status note and contribution guidance that routes changes to the owning team. Repository Checklist may still recommend a security policy, docs, and changelog even when public contribution files are not the main concern.

Research dataset or reproducibility project. A Data or research project profile with a DOI in Citation DOI should add Data and Reproducibility notes plus a Citation section. The checklist should include CITATION.cff so the maintainer can mirror citation details outside the generated Markdown.

Badge troubleshooting. If Include quality badges is on but Repository URL is empty or not a GitHub repository URL, README notes warns that CI badge links need a GitHub repository URL. Add a valid repository URL or turn badges off before copying the draft.

FAQ:

Does the generator check my repository?

No. It builds README Draft, Section Audit, Repository Checklist, and JSON from the values entered on the page. Verify commands, paths, badges, and support files in the actual repository before publishing.

Why is my readiness score below 100%?

At least one audit row is Check, Missing, or Optional with partial credit. Open Section Audit and use the Next copy column to decide which input needs more detail.

Should I trust the generated license section?

Treat it as README wording only. The selected license label should match the repository's actual license text, and custom or proprietary terms should be reviewed by the responsible owner.

Why did badge output not appear?

Badge Markdown appears only when Include quality badges is on and the repository URL can be parsed as a GitHub repository. Otherwise the warning list asks you to add a compatible URL or skip badges.

Does the tool push README text to GitHub?

No. The page creates Markdown and review data for copy or download actions. It does not call the GitHub API or commit files to a repository.

Glossary:

README profile
The selected project type that decides the profile-specific section title and review emphasis.
Contribution posture
The setting that decides whether the README invites public contributions, routes internal changes, or omits contribution copy.
Section Audit
A review table that scores README areas as Ready, Check, Missing, or Optional.
Repository Checklist
A follow-up table for repository support files such as LICENSE, contribution guide, code of conduct, security policy, changelog, docs, CI workflow, and citation file.
SPDX-style label
A concise license identifier format used to name common software licenses consistently.

References: