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.
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.
What does the README health score measure?
Why a single number?
What grade should I aim for?
Is the score deterministic?
Can I tune the weights?
Is the README uploaded?
Related tools
More free browser tools in the same workflow.
Use the API
Automate this workflow in your app with the same engine that powers these browser tools.
New to the platform? Start with the API quickstart, then try a live request in the API playground.
Explore the API platform