readme-score

Score any README file 0-100 based on documentation quality criteria. Zero dependencies.

Table of Contents

• Installation
• Usage
• Scoring Criteria
• API
• Contributing
• Changelog
• License

Installation

npm install -g readme-score

Or use directly with npx:

npx readme-score

Usage

# Score README in current directory
readme-score

# Score a specific file
readme-score ./README.md

# Score a GitHub repository
readme-score https://github.com/facebook/react

The tool produces color-coded terminal output with a visual progress bar, checkmarks for passing criteria, and marks for missing sections.

Scoring Criteria

| Criteria | Points | |---|---| | Has title/heading | 5 | | Has description | 10 | | Has installation instructions | 10 | | Has usage examples | 15 | | Has code blocks | 10 | | Has badges | 5 | | Has license section | 5 | | Has contributing section | 5 | | Has table of contents | 5 | | Length > 500 chars | 5 | | Length > 1000 chars | 5 | | Length > 2000 chars | 5 | | Has screenshots/images | 5 | | Has API/reference docs | 5 | | Has changelog/version info | 5 | | Total | 100 |

API

Use readme-score programmatically:

const { score } = require('readme-score/lib/scorer');
const result = score('# My Project');
console.log(result.total);

score(content)

Returns an object with total, max, and results array.

Contributing

Contributions welcome! Fork, branch, commit, PR.

Changelog

1.0.0

• Initial release with 15 scoring criteria
• CLI supporting local files, URLs, and GitHub repos
• Zero dependencies

License

MIT