Every check and threshold
Read from the code that scores, so this page and the score cannot disagree. Change a number in the source and both move.
The checks
| Sections | For each section below, a heading whose text is one of its synonyms or starts with one as whole words. The heading matching the strongest synonym wins; the title does not count. A missing section's fix names the line to add it at: after the nearest section before it in the order below. |
|---|---|
| Title near the top | A # heading or <h1> within the first 5 non-empty lines, outside code. |
| Install command | A command that installs the project, in a code block or inline code, within the first 40 lines. curl … | sh counts only when the line names the project, so another tool's installer does not. |
| Picture of it working | An image within the first 20 lines that is not a badge. |
| Badges before the first code block | At most 6 badge images (shields.io, badgen, badge.fury.io, any /badge path) above the first code block. |
| Words before the first code block | At most 250 words above the first code block, not counting images, HTML tags and link targets. |
| Flesch reading ease | 206.835 − 1.015 × words per sentence − 84.6 × syllables per word, over the prose (code, HTML, tables, images and link targets removed; a line without end punctuation ends a sentence). 60 or more earns every point, 30 or less none, linear in between. |
| Quickstart block | The first shell block (bash, sh, console, powershell…, or a block with no language) with a command that installs the project. |
| Commands in the quickstart | At most 6. a && b and a; b are two; comments, blank lines and output after a $ prompt are none. |
| Translations give the same commands | README.<lang>.md, README-<lang>.md or README_<lang>.md next to the README or in <code>docs</code>, <code>i18n</code>, <code>translations</code>, <code>locales</code>, <code>l10n</code>, <code>readme</code>: each one's quickstart must have the README's commands in the same order. <code>cd</code>, <code>mkdir</code>, <code>pushd</code>, <code>popd</code> lines may differ, since a translation may name its folder in its own language. Points shrink with the share that differ. |
| Relative links resolve | Every [text](path), , [id]: path, <a href> and <img src> outside code that is a path must name a file or folder in the repository with that exact case. 1 point off per broken link. |
| #anchors match a heading | Every link to #anchor (or to the README's own file#anchor) must match a heading's GitHub anchor or an HTML id. Anchors into other files are not checked. |
| One tagline everywhere | The README H1, the descriptions in package.json, pyproject.toml, Cargo.toml and composer.json (and a nested package.json that is published or has a bin), the first > line of llms.txt files and the GitHub About description, compared after dropping case, punctuation, URLs and a leading "<name>:". Points by distinct wordings: 3, 1.5, 0. |
| One spelling of the name | The H1's first word is the name. Other capitalisations of it in the README's prose (FLISK, FLisk for Flisk) are listed with their first line; code, link targets, URLs, paths and all-lower-case uses (the command) are left out. |
| Website leads with the README's command | The first <name> <subcommand> the README's quickstart runs (flisk project), against the first the website's <pre> and <code> elements show (flisk import); without one, the first command that is not an install, cd or mkdir. |
| Website shows the README's install command | The README's first install command against the website's, compared after dropping a $ prompt and repeated spaces. |
| Website headline matches the README | The website is the repository's homepage on GitHub, else "homepage" in package.json, or the address given with a pasted README. Its og:title, <title> and first <h1>, whole and split at |, -, —, · and :, are compared with the README H1 after the same normalising as taglines; one must equal it, or hold it whole (or be held by it) when both have three words or more. |
| Website description matches the README pitch | The key words of the website's meta description (or og:description), against those of the README's pitch: the H1 and the prose after it up to the first section or code block, at most 120 words. Key words are three letters or more, stopwords and the project's names left out. 50% of the website's in the README earns every point, less earns a share. Only http and https on public addresses are read, 3 redirects at most. |
Thresholds and points
| Group | Constant | Value |
|---|---|---|
| First screen | H1_WITHIN_NONEMPTY_LINES | 5 |
| First screen | INSTALL_WITHIN_LINES | 40 |
| First screen | IMAGE_WITHIN_LINES | 20 |
| First screen | MAX_BADGES_BEFORE_CODE | 6 |
| First screen | MAX_PROSE_WORDS_BEFORE_CODE | 250 |
| Readability | READING_EASE_FULL_MARKS | 60 |
| Readability | READING_EASE_ZERO | 30 |
| Readability | LONG_SENTENCE_WORDS | 25 |
| Quickstart | MAX_QUICKSTART_COMMANDS | 6 |
| Links | POINTS_LOST_PER_BROKEN_LINK | 1 |
| Tagline | TAGLINE_POINTS_BY_DISTINCT | 3, 1.5, 0 |
| Website | WEBSITE_PITCH_MIN_OVERLAP | 0.5 |
| Website | README_PITCH_WORDS | 120 |
| Points | POINTS.sections | 35 |
| Points | POINTS.firstScreenEach | 4 |
| Points | POINTS.readability | 10 |
| Points | POINTS.quickstartFound | 2 |
| Points | POINTS.quickstartLength | 3 |
| Points | POINTS.translations | 5 |
| Points | POINTS.fileLinks | 5 |
| Points | POINTS.anchors | 5 |
| Points | POINTS.tagline | 3 |
| Points | POINTS.nameSpelling | 2 |
| Points | POINTS.websiteHeadline | 3 |
| Points | POINTS.websitePitch | 3 |
| Points | POINTS.websiteLead | 2 |
| Points | POINTS.websiteInstall | 2 |
Section weights by project type
3: required · 2: recommended · 1: nice to have. A section's points are 35 × its weight ÷ the type's total weight.
| Section | CLI tool | Library | Full-stack app | Backend API |
|---|---|---|---|---|
| Overview | 2 | 2 | 3 | 2 |
| Key features | 2 | 2 | 2 | 1 |
| Prerequisites | 2 | 1 | 3 | 3 |
| Installation | 3 | 3 | 3 | 3 |
| Usage or commands | 3 | 3 | 2 | 3 |
| Configuration | 2 | 1 | 3 | 3 |
| Examples | 2 | 3 | 1 | 2 |
| Troubleshooting | 1 | 1 | 2 | 2 |
| Roadmap | 1 | 1 | 1 | 1 |
| Contributing | 2 | 2 | 2 | 2 |
| License | 3 | 3 | 3 | 3 |
Synonyms
| Overview | overview, introduction, intro, about, what is, whats, what it does, description, summary, background, motivation |
|---|---|
| Key features | features, key features, main features, feature list, highlights, why, what you get, capabilities, benefits, whats included |
| Prerequisites | prerequisites, prerequisite, pre requisites, requirements, system requirements, dependencies, before you begin, before you start, what you need, you will need, youll need, supported platforms, compatibility |
| Installation | installation, install, installing, setup, set up, setting up, getting started, get started, quick start, quickstart, download, downloads |
| Usage or commands | usage, commands, command reference, command line, cli, api, reference, endpoints, routes, how to use, using, use, flags, running, run |
| Configuration | configuration, config, configuring, configure, settings, options, environment variables, environment, env, env vars, customization, customisation, customizing, customising |
| Examples | examples, example, demo, demos, samples, sample, recipes, tutorial, tutorials, cookbook, showcase, use cases |
| Troubleshooting | troubleshooting, troubleshoot, faq, faqs, frequently asked questions, common issues, common problems, known issues, debugging, getting help, help, problems |
| Roadmap | roadmap, road map, plans, future plans, whats next, todo, to do, upcoming, milestones |
| Contributing | contributing, contribute, contribution, contributions, how to contribute, development, developing, local development, hacking, building from source, build from source |
| License | license, licence, licensing, copyright |
Project type
From package.json first ("bin": CLI tool; Next.js, Nuxt, SvelteKit, Remix or Astro, or a front-end framework with a server one: full-stack app; Express, Fastify, Hono, Koa or NestJS alone: backend API; "main" or "exports": library), then pyproject.toml, Cargo.toml and go.mod, then a Compose file (app). A pasted README is read for signals, such as npm install -g for a CLI or GET /users for an API; with none it is scored as a CLI tool. The result page lets you pick another.
Grades
A: 90+ · B: 80+ · C: 65+ · D: 50+ · F: 0+
Patterns
Install command
(?:^|[\s;&|(`$])(?:(?:npm|pnpm|yarn|bun)\s+(?:install|i|add|create)\b|npm\s+init\s+\S|(?:npx|pnpx|bunx)\s+\S|(?:pnpm|yarn)\s+dlx\s+\S|(?:pip3?|pipx|poetry|pdm|conda|mamba|uv\s+pip|uv\s+tool)\s+(?:install|add)\b|uvx?\s+(?:add|run)\b|uvx\s+\S|cargo\s+(?:install|add|binstall)\b|go\s+(?:install|get)\b|brew\s+install\b|(?:gem|bundle)\s+(?:install|add)\b|composer\s+(?:require|create-project|global\s+require)\b|dotnet\s+(?:add\s+package|tool\s+install)\b|(?:sudo\s+)?(?:apt|apt-get|dnf|yum|pacman|apk|zypper|snap|flatpak|winget|scoop|choco|nix-env|port)\s+(?:install|add|-S)\b|nix\s+(?:profile\s+install|run)\b|deno\s+(?:install|add)\b|docker\s+(?:run|pull)\b|docker[\s-]compose\s+up\b|git\s+clone\b|helm\s+install\b|mix\s+archive\.install\b|cabal\s+install\b|opam\s+install\b|luarocks\s+install\b)
Badge
shields\.io|badgen\.net|badge\.fury\.io|[/.]badges?(?=[/.?#]|$)
Shell languages
bash, sh, shell, zsh, fish, console, terminal, shell-session, shellsession, powershell, pwsh, ps1, cmd, bat
Infrastructure words
Listed with their counts, not scored: docker, compose, tilt, kubernetes, k8s, helm, traefik, container, containers, cluster, ingress, manifest, yaml, orchestration.