README Health Score
Audit your README — get a 0–100 quality score and letter grade
Combine heading hierarchy, GFM compliance, image alt text, link integrity, and task completion into a single weighted score. Drop-in CI-style gate for public READMEs and internal docs alike.
Score
100
out of 100
A+
- Heading hierarchyweight 20 · 100%
Outline is consistent.
- GFM complianceweight 30 · 100%
5/5 checks pass.
- Image alt textweight 15 · 100%
No images found.
- Link integrityweight 25 · 100%
0 broken, 0 warning(s).
- Open task itemsweight 10 · 100%
No tasks.
No issues detected — this README is in great shape.
How to use the README health score
- Paste your README or open the file with the picker.
- The big score card shows the overall 0–100 score and a letter grade.
- The breakdown lists each dimension with its individual percentage and weight.
- The issue list at the bottom shows actionable problems — fix them, paste again, watch the score rise.
Why score a README?
A great README does five jobs:
- Tells you what the project does at a glance (heading hierarchy).
- Renders correctly on GitHub (GFM compliance).
- Has accessible images (alt text).
- Doesn't send you down dead links (link integrity).
- Reflects honest status for any task lists (completion).
Each dimension fails silently when ignored — a broken anchor doesn't crash anything, but it costs reader trust. The aggregate score makes the cost visible.
What gets weighted, and why
| Dimension | Weight | Why |
|---|---|---|
| Heading hierarchy | 20% | Spine of accessibility, SEO, and TOC generation. |
| GFM compliance | 30% | Five pre-publish checks; broad coverage of issues. |
| Image alt text | 15% | Accessibility — affects real users right now. |
| Link integrity | 25% | Broken links break trust faster than any other defect. |
| Task completion | 10% | For roadmap READMEs; ignored when no tasks present. |
Score → grade mapping
| Score | Grade |
|---|---|
| 95–100 | A+ |
| 85–94 | A |
| 75–84 | B |
| 65–74 | C |
| 50–64 | D |
| 0–49 | F |
Pre-merge workflow
- Run the health score on your branch's README.
- Note the grade.
- Fix the top 3 issues.
- Run again. If grade improved and no regressions, merge.
That's the entire workflow — a 60-second gate that compounds quality across hundreds of READMEs over time.
Companion tools
- Markdown Link Checker — dig into link issues.
- Markdown Image Audit — dig into image issues.
- Heading Hierarchy Auditor — dig into outline issues.
Privacy & data
The score is computed inside your browser. No content is uploaded.
Frequently asked questions
- Five weighted dimensions: (1) heading hierarchy (20%), (2) GFM compliance — code fences, alt text, etc. (30%), (3) image alt text completeness (15%), (4) link integrity — broken anchors, empty links, malformed mailto (25%), (5) task list completion (10%). The weighted sum gives a 0–100 score and an A+ to F grade.
- Individual audits are useful for digging in, but they don't answer 'is my README good enough?' at a glance. A single grade is a fast forcing function — anything below an A signals work to do. Use it as a CI-style gate before merging README changes.
- A or A+ for any public-facing README. B is acceptable for internal docs. Below C means a reader will likely encounter a broken link, missing alt text, or a confusing heading jump.
- Yes. Given the same input, the score is identical every time. The components are pure functions over the document content — no network calls, no randomness, no AI judgement.
- Not in the UI yet — the defaults reflect typical README priorities (link integrity and GFM compliance carry the most weight). The underlying functions are exported from our toolkit, so you can build a custom score in CI by combining them.
- No. All audits run inside your browser. Nothing leaves the tab.