{{ summaryTitle }}
{{ computation.values.readiness }}% ready

{{ summaryLine }}

Profile{{ profileLabel }} Sections{{ computation.values.section_count }} Review notes{{ computation.values.warning_count }}
The active default adds no lifecycle warning; other choices add an explicit status note.
Open source expects contribution files; internal and closed modes change the generated guidance.
The neutral default omits the contents list; include it for a longer generated draft.
{{ include_toc ? 'Included' : 'Omitted' }}
Badges use the repository URL and remain secondary to setup and usage instructions.
{{ include_badges ? 'Included' : 'Omitted' }}
{{ computation.values.markdown }}
AreaStatusSignalNext stepCopy
{{ row.area }}{{ row.status }}{{ row.signal }}{{ row.next_copy }}
Repository itemStatusWhy it mattersNext actionCopy
{{ row.item }}{{ row.status }}{{ row.reason }}{{ row.next_action }}
Changelog Generator Turn release notes, changelog sections, or Conventional Commit subjects into grouped Markdown with SemVer signals and pre-publish checks.
Release Notes Generator Turn commits, pull requests, or release bullets into audience-ready Markdown with grouped changes, parser warnings, and publication checks.
Markdown Previewer Preview Markdown locally with GFM or CommonMark rules and sanitized HTML, plus structure checks and review notes before reusing the markup.
Markdown to HTML Converter Convert Markdown into a reusable HTML fragment or full document with flavor selection, raw-HTML controls and a sanitized local preview.

A repository README is often the first explanation a user, contributor, or future maintainer sees. Its main job is to help that reader decide what the project is, whether it fits their need, and how to reach a first successful result. A project can have excellent code and still be hard to adopt when the setup assumptions or usage path are missing.

The most useful opening names the project, states the problem it solves, and gives enough context to identify the intended audience. Setup instructions then bridge the gap between interest and a working installation. A short, realistic usage example is stronger than a long feature list because it proves what success looks like.

Different repositories need different supporting sections. A command-line tool benefits from options and shell examples; a service needs endpoints and operations notes; a data project needs provenance and reproducibility guidance. Public projects also need clear contribution, conduct, support, security-reporting, and licensing routes. Internal projects may replace community guidance with ownership and operational expectations.

  • Readers need orientation: purpose, audience, status, and the fastest useful example.
  • Operators need repeatability: prerequisites, installation commands, configuration, testing, and support.
  • Contributors need boundaries: contribution rules, conduct expectations, security reporting, and reuse terms.

A README should remain an entry point rather than absorbing every design note or tutorial. Longer material belongs in dedicated documentation, while the README keeps the quick path accurate and links to the deeper source.

Generated Markdown is a draft, not evidence that the repository actually contains the commands, workflow files, license text, or policy documents it names. Every link and instruction must be checked against the repository before publication.

How to Use This Tool:

Choose the profile that matches the repository's real job, then supply facts that a new reader can verify.

  1. Select the README profile and enter the exact Project name, a useful short description, and the repository URL when one exists.
  2. Add concrete features, prerequisites, installation commands, and one usage example that reaches a successful result. Use the profile-specific fields for API, options, data, or operations notes.
  3. Choose the real project status, license label, and contribution posture. Add support and security-policy paths only when those destinations will exist in the repository.
  4. Read the Section audit and Repository checklist, correct missing or weak facts, then inspect the generated Markdown before committing it as README.md.

Interpreting Results:

The readiness percentage is a local coverage heuristic. A high score means the draft includes the weighted facts this generator checks; it does not prove that commands work, links resolve, badges report the right workflow, or legal terms match the project.

  • Treat Missing as a gap in a high-value reader path such as installation or usage.
  • Treat Check as a prompt for human judgment, especially for short descriptions, incomplete community files, non-GitHub repository URLs, and vague custom licenses.
  • Use the repository checklist to create or verify companion files. The draft links to those files but does not create them.

Technical Details:

README generation is a structured Markdown transformation followed by a weighted content audit. Blank optional inputs suppress their sections, while required reader paths receive placeholder or missing-state guidance so the draft does not silently look complete.

Transformation Core:

The selected profile changes the profile-specific section title, not the underlying Markdown rules. Line-based facts become bullets, commands become fenced shell blocks, and environment-variable pairs become a table.

Profile Profile section Emphasis
Library/package API Reference Public interfaces and integration notes
CLI tool Options Commands, flags, and shell behavior
Web app/API API Endpoints and service use
Data/research Data and Reproducibility Data sources, methods, and repeatable results
Internal service Operations Ownership, runtime, and support expectations

Non-active status choices add a visible status note near the top. A table of contents appears only when requested and when the draft has at least five second-level sections. GitHub CI badges require a recognizable GitHub owner and repository path; other repository URLs do not receive that badge.

Rule Core:

Audit area Ready condition Weight
Opening description At least 60 characters 16
Installation At least one command line 16
Usage At least one example line 16
Project name and features A name and at least three feature bullets 20
License, support, and community files Specific reuse terms, a help route, and contribution files appropriate to the chosen posture 21
Requirements, profile notes, repository URL, security policy, and long-form docs Evaluated as ready or optional according to the supplied facts 29

Formula Core:

The readiness score is the rounded share of audit weight earned. Optional or partial rows can earn some credit, so it is not simply the percentage of rows marked Ready.

Readiness = round ( earned audit weight possible audit weight × 100 )

The displayed value is a whole-number percentage. The draft also counts second-level sections, whitespace-delimited words, lines, and up to the first four audit warnings, with an additional warning when badges are requested for a non-GitHub repository URL.

Accuracy and Privacy Notes:

Project facts are processed in the browser; the generator does not inspect the repository or send its contents to a server. That privacy boundary also explains the main accuracy limit: every generated claim comes from the text entered by the user.

  • Run installation, test, and usage commands in a clean environment before publishing them.
  • Confirm every relative path and external URL, especially contribution, conduct, security, documentation, and support links.
  • A license label is not a license grant. Add the matching full license text and obtain appropriate legal review for custom or proprietary terms.
  • Generated badges assume a GitHub Actions workflow named ci.yml; change or remove the badge when the repository uses another workflow.

References: