readme-lint-cli

Lint your README.md for common quality issues. Zero dependencies. CI/CD ready.

Catches missing titles, empty sections, dead links, placeholder text, inconsistent headings, and more. Helps you ship better documentation every time.

Installation

npm install -g readme-lint-cli

Or use it locally in a project:

npm install --save-dev readme-lint-cli

Usage

# Lint README.md in current directory
readme-lint

# Lint a specific file
readme-lint docs/GUIDE.md

# JSON output for CI pipelines
readme-lint --json

# Strict mode (exit 1 on any warning)
readme-lint --strict

# Auto-fix trailing spaces and heading levels
readme-lint --fix

# Use a custom config file
readme-lint --config .readmelintrc.json

CLI Options

| Flag | Description | |------|-------------| | -h, --help | Show help message | | -v, --version | Show version number | | --json | Output results as JSON | | --strict | Exit with code 1 on any warnings or errors | | --no-color | Disable ANSI color output | | --config <file> | Path to config file (.readmelintrc.json) | | --fix | Auto-fix trailing spaces and heading levels |

Rules

All 13 built-in rules with their default severity levels:

| Rule | Default | Description | |------|---------|-------------| | has-title | error | README must start with an H1 heading | | has-description | error | Must have text after the first heading | | no-empty-sections | error | No headings followed by another heading with no content | | no-dead-links | error | Detects empty, placeholder, or malformed URLs | | has-install | warning | Should have an Installation/Install/Getting Started section | | has-usage | warning | Should have a Usage/How to Use/Examples section | | has-license | warning | Should mention a license somewhere | | no-todo-placeholders | warning | No leftover placeholder markers in the document | | consistent-headings | warning | Heading levels should not skip (H1 to H3 without H2) | | has-code-blocks | warning | Technical READMEs should have at least one code block | | no-duplicate-headings | warning | No two headings with the exact same text | | no-trailing-spaces | info | Lines should not have trailing whitespace | | max-line-length | info | Warn on lines longer than 120 characters (configurable) |

Configuration

Create a .readmelintrc.json file in your project root to customize rules:

{
  "rules": {
    "no-dead-links": "error",
    "has-title": "error",
    "max-line-length": ["warning", { "max": 100 }],
    "has-code-blocks": "off",
    "no-trailing-spaces": "off"
  }
}

Severity levels: "error", "warning", "info", "off"

Rules with options use the array format: ["severity", { ...options }]

Output

Terminal output:

README.md
  L1   error    has-title          Missing H1 title at the start of the document
  L15  warning  no-empty-sections  Empty section: "Contributing" has no content
  L42  info     no-trailing-spaces Trailing whitespace found

3 problems (1 error, 1 warning, 1 info)

JSON output (with --json):

{
  "file": "README.md",
  "issues": [
    { "line": 1, "severity": "error", "rule": "has-title", "message": "Missing H1 title..." }
  ],
  "summary": { "total": 1, "errors": 1, "warnings": 0, "info": 0 }
}

CI/CD Integration

Add to your GitHub Actions workflow:

name: Lint README
on: [push, pull_request]

jobs:
  readme-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npx readme-lint-cli --strict

Or add to your package.json scripts:

{
  "scripts": {
    "lint:readme": "readme-lint --strict"
  }
}

Auto-Fix

The --fix flag automatically corrects:

• Trailing whitespace on all lines
• Skipped heading levels (e.g., H1 followed by H3 becomes H1 followed by H2)

readme-lint --fix

Exit Codes

| Code | Meaning | |------|---------| | 0 | No errors (warnings/info may be present) | | 1 | Errors found, or warnings found in --strict mode |

License

MIT