stolt/readme-lint

A library and CLI for linting, spell-checking, and creating README.md files.

v0.2.0 2025-11-05 01:58 UTC

Requires

• php: >=8.1
• symfony/console: ^7.3
• symfony/process: ^7.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.82
• mockery/mockery: ^1.6
• peckphp/peck: ^0.2.0
• phpunit/phpunit: ^12.2
• shipmonk/composer-dependency-analyser: ^1.8
• stolt/lean-package-validator: ^4.4

MIT

• Raphael Stolt

• php
• cli
• linter
• lint
• dev
• readme
• README.md

README

readme-lint

This library and its CLI supports you in linting README.md Markdown files via PHP. For inspiration for good READMEs, please have a look at the Awesome README repository.

Installation and usage

composer require --dev stolt/readme-lint

Available CLI commands

The following list shows the currently three available CLI commands to interact with a README.md file.

php bin/readme-lint list

readme-lint 0.0.2

Available commands:
  init        Create an initial README.md file in the current working directory
  lint        Lint a README.md file for common quality issues
  spellcheck  Check a README.md file for wording or spelling mistakes

Available lint rules can be found in the Rules directory.

Configuration

To configure the lint rules to apply, you have several options:

1. Create a .readme-lint.php file in the root of your project, which will be used as a default configuration when present.

2. Create a some-readme-lint-configuration-file.php file which you pass to the CLI via an option.

php bin/readme-lint lint --config=some-readme-lint-configuration-file.php

1. Pass a list of rules as a comma-separated string to the CLI. You can use FQCNs or base names for the rules to apply.

php bin/readme-lint lint --rules Stolt\ReadmeLint\Rules\LogoPresenceRule,NoTodoCommentRule

Note

To add custom lint rules, you must first create classes which implement the Stolt\ReadmeLint\Rule\RuleInterface interface and then make them available via your readme-lint configuration file like shown next.

<?php declare(strict_types=1);

use Stolt\ReadmeLint\Configuration;
use Stolt\ReadmeLint\Linter;

$configuration = new Configuration(new Linter(getcwd()));
$configuration->setCustomRulesDirectory(
    '/some/path/to/custom/rules',
    'Custom\Rules\Namespace'
)->addRulesToApply(['CustomRuleA', 'CustomRuleB', 'NoTodoCommentRule']);

return $configuration;

Running tests

composer test

License

This library and its CLI are licensed under the MIT license. Please see LICENSE.md for more details.

Changelog

Please see CHANGELOG.md for more details.

Contributing

Please see CONTRIBUTING.md for more details.