docdecay

Scan your docs for freshness, broken links, and staleness. Get a quick health report of your documentation.

Install

npm install -g @aaaaorg/docdecay

Usage

# Scan current directory
docdecay

# Scan specific directory
docdecay ./docs

# JSON output (great for CI)
docdecay --json

# Skip link checking (faster)
docdecay --no-links

# Custom threshold (default: 50)
docdecay --threshold 70

# Ignore files
docdecay --ignore "**/archive/**"

# Custom max age (default: 365 days)
docdecay --max-age 180

What it does

• Freshness scoring — Each .md file gets a 0-100 score based on when it was last modified (via git history, falling back to file mtime)
• Broken link detection — Finds broken internal links (relative paths) and optionally checks external URLs
• Word count & reading time — Know how long each doc takes to read
• CI-friendly — Exits with code 1 if stale files or broken links are found. Use --json for machine-readable output.

Example output

📄 Documentation Freshness Report

┌──────────────────┬───────┬──────────┬───────┬───────────┐
│ File             │ Score │ Days Old │ Words │ Read Time │
├──────────────────┼───────┼──────────┼───────┼───────────┤
│ getting-started  │ 95    │ 18       │ 1200  │ 6 min     │
├──────────────────┼───────┼──────────┼───────┼───────────┤
│ api-reference    │ 42    │ 211      │ 3400  │ 17 min    │
└──────────────────┴───────┴──────────┴───────┴───────────┘

Summary: 2 files scanned, 1 stale (< 50)

🔗 All links OK

Options

| Flag | Default | Description | |------|---------|-------------| | -t, --threshold <n> | 50 | Minimum freshness score | | --json | false | Output JSON | | --no-links | false | Skip link checking | | --ignore <glob> | — | Ignore files matching glob | | --max-age <days> | 365 | Days after which score = 0 |

License

MIT