readme-validator

The reference implementation of the README Specification (RRS). A free CLI tool to enforce quality standards.

npx readme-validator check .

Table of Contents

• Summary
• Why
• Features
• Project Status
• Installation
• Quickstart
• Usage
• Configuration
• Documentation
• Limitations
• Support
• Prior art
• Contributing
• Acknowledgements
• Contact
• License

Summary

Based on extensive research into documentation standards across thousands of open-source repositories — from one-person weekend projects to critical infrastructure maintained by hundreds of contributors — the Repository README Specification codifies what the best READMEs have in common and what the worst ones consistently lack. The readme-validator turns that knowledge into an automated tool: point it at any README.md and get instant, actionable feedback on structure, completeness, ordering, accessibility, and compliance.

Why

Most README files are written ad hoc, without structure or consistency. They drift out of date, omit critical sections, bury prerequisites, and fail to orient newcomers. There is no widely adopted standard for what a README must include. The README.md Specification fills that gap by defining normative rules for structure and quality. The readme-validator enforces these rules — automatically, reproducibly, and at any strictness level you choose.

Features

• 📐 44 built-in rules — across structural, ordering, formatting, accessibility, repository, and heuristic categories
• 🎛️ Six presets — minimal, recommended, strict, library, cli, and research for different strictness profiles
• ⚙️ YAML configuration — with file discovery (.readmerc.yml), inheritance, and per-rule overrides
• 📊 Weighted scoring — 100-point scale with per-category breakdown and adaptive bonuses for RRS best practices
• 🏆 Compliance levels — immediate classification into none, minimal, recommended, or strict tiers
• 🛡️ GitHub Style Guide compliance — automated checks for alerts, keyboard shortcuts, and bold text limits
• ♿ Accessibility & Hygiene — decorative image detection, alt-text quality, and shell prompt cleanup
• 📂 Monorepo support — multi-README scanning with shared or individual configuration

Project Status

Stable — v1.1.0. The validator is in full parity with the RRS v1.0.0. The CLI interface and configuration schema are stable and follow semantic versioning.

Installation

Requires Node.js >= 18.

npm install -g readme-validator

Or run without installing using npx:

npx readme-validator check .

Quickstart

Validate your current repository against the recommended preset:

readme-validator check .

Expected output for a compliant repository:

README validation passed

Compliance level: recommended
Score: 97
Errors: 0
Warnings: 2

To see a detailed score breakdown:

readme-validator score .

Usage

CLI Commands

| Command | Description | | --- | --- | | check [target] | Validate a repository or README file | | score [target] | Show validation score and per-category breakdown | | init | Create a default .readmerc.yml configuration | | explain <ruleId> | Show detailed documentation and suppression syntax for a rule | | list-rules | List all available validation rules with descriptions | | **print-config | Show the fully resolved configuration after merging presets |

Global Flags

| Flag | Effect | | --- | --- | | --preset <name> | Use a specific profile (e.g., strict, library) | | --format <type> | Output format (text, json, yaml) | | --config <path> | Use a specific configuration file | | --fail-on-warnings | Exit with code 1 if any warnings are found | | --quiet | Suppress non-error output |

Command Examples

Run the validator with specific options:

npx @rhythmus/readme-validator check . --preset strict --format json

Example output (JSON):

{
  "complianceLevel": "strict",
  "score": 100,
  "errors": 0,
  "warnings": 0
}

Rule Suppression

Suppress rules for specific blocks using HTML comments:

<!-- readme-validator-disable-next-line missing_proof -->
<!-- readme-validator-disable missing_installation -->
...
<!-- readme-validator-enable missing_installation -->

Configuration

Customise the validator via a .readmerc.yml file in your repository root:

preset: recommended

rules:
  missing_proof: warning
  vague_summary: false
  oversized_code_example:
    severity: info

limits:
  maxBadges: 14
  maxCodeBlockLines: 50

Documentation

• README.md Specification — the full normative standard
• Interactive Playground — web-based validation tool
• Run readme-validator explain <ruleId> for per-rule guidance

Limitations

• Targets Markdown-formatted README.md files only; reStructuredText and AsciiDoc are out of scope.
• Section detection relies on heading text matching; unconventional names require configuration aliases.
• Readability metrics are calibrated for English prose; scores may vary for other languages.

Support

Open an issue in the source repository for bug reports, feature requests, or rule clarifications.

Prior art

• README.md Specification (RRS) — the formal normative standard this tool implements.
• standard-readme — provide conceptual inspiration for mandatory sections and checklists.
• Make a README — community guide for documentation patterns.

Contributing

Contributions are welcome. Please refer to CONTRIBUTING.md in the parent repository for guildelines on submitting rule improvements or bug fixes.

Acknowledgements

Δόξα τω Θεώ! Many thanks to the open-source community for the documentation patterns that informed this tool.

Contact

• Author: Dr Wouter Soudan

License

This tool is licensed under the MIT License.