"Code is written for machines to execute, but documentation is written for humans to understand."
README Scorer is an automated Quality Assurance (QA) utility designed to evaluate the comprehensiveness and technical maturity of README.md files. Built with a focus on developer experience and documentation standards, it ensures your repository’s "front door" is always welcoming and informative.
Documentation is often the most neglected part of software development. README Scorer addresses this by programmatically auditing markdown files. It doesn't just check for keywords; it analyzes structure, content density, and the presence of critical technical artifacts like code blocks and contact links.
- Architecture: Modular TypeScript design following SOLID principles.
- Intelligence: Built-in synonym mapping for flexible section identification.
- Visuals: Rich terminal output with ANSI colors and clear status indicators.
- 🔍 Smart Section Mapping: Recognizes various headers like "Setup", "Getting Started", and "Installation" under a unified logic.
- 📈 Dynamic Scoring Engine: A strict 0-100 matrix based on content depth and technical requirements.
- 🛠️ Content Validation: Verifies that sections aren't just empty headers but contain meaningful data (minimum character counts and code block detection).
- 🤖 CI/CD Integration: Supports
--format jsonfor automated pipeline checks. - 💡 Actionable Insights: Provides specific suggestions to improve your documentation score.
- Runtime: Node.js
- Language: TypeScript
- CLI Framework: Commander.js
- Formatting: Chalk (for high-fidelity CLI colors)
- Parsing: Custom Markdown AST-based Regex Logic
- Node.js (v18 or higher)
- npm or yarn
-
Clone the repository:
git clone [https://github.com/willbyers1/readme-scorer.git](https://github.com/willbyers1/readme-scorer.git) cd readme-scorer -
Install dependencies:
npm install
-
Build the project:
npm run build
Run the tool against any Markdown file by providing its path:
CLICK TO USE If the link doesn't work here is the URL: https://willbyers1.github.io/README-SCORER/
Created By Mert Batu Bülbül
- 🎓 Computer Engineering Undergraduate * 💻 Full Stack Developer & AI Enthusiast *