{u.date}
{u.tag}
{u.title}
{u.body}
A zero-config CLI that walks a documentation folder, runs the
Flesch–Kincaid test on every .md and{" "}
.adoc file, and tells you exactly how
hard your docs are to read — with sentence, word, syllable, and
acronym breakdowns to back it up.
{f.b}
Recent releases and what shipped. Sourced from git log, not marketing.
{u.body}
The pipeline, end to end. Read once, explain it to a teammate.
{s.b}
{i < arr.length - 1 && →}Hover or focus a band to see where your prose lands. Each band carries both a label and a US grade level, so the meaning never relies on colour alone.
Further reading — the original Flesch–Kincaid Wikipedia article and Rudolf Flesch's 1948 A new readability yardstick.
Two install paths, one command to run, two things to expect back.
.adoc or .md files found."The CLI didn't find anything to score at the path you gave it. Confirm you're pointing at the right folder, and that your docs are not nested inside an ignored directory. readability-ts . from the docs folder is the safest sanity check.
The tool prepends a comment to each scored file, so it needs write access to the folder you scan. Run it from a directory you own, or chmod the docs tree.
If you installed via npm i -g, make sure your npm global bin directory is on PATH. Check it with npm bin -g. If you installed from source, you need to run npm link from inside the repo.
Illustrative scores by genre — to calibrate your own.
To give the numbers texture, here is roughly where common writing genres tend to score. These are indicative ranges, not measurements of any specific publication. Run the CLI against your own docs to get the real picture.
Illustrative — based on widely-reported ranges for these genres. Your mileage will vary by author, audience, and era.
{/* Histogram */}A sample distribution from scanning a 47-file documentation set. The CLI doesn't draw this — but it gives you all the numbers to make your own.
Score every PR. Catch regressions before they ship.
{`# .github/workflows/readability.yml
name: Readability
on: [pull_request]
jobs:
score:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm i -g @alexneri/readability-ts
- run: readability-ts ./docs
- uses: actions/upload-artifact@v4
with:
name: scores
path: docs/scores.txt`}
Pair with a tiny shell guard to fail the build if the average drops below your target.
{`# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
# Score docs that changed in this commit
git diff --cached --name-only --diff-filter=ACM \\
| grep -E '\\.(md|adoc)$' \\
| xargs -I{} readability-ts {}`}
Annotates only the files you're committing. Keeps the rest of the tree untouched.
Different tools, different jobs. Here's where each shines.
Prose linters check rules — banned words, passive voice, inconsistent terms. Readability scoring gives you a single number for density, file by file. They complement each other; this isn't a replacement.
The questions that come up most.
{f.a}
readability-ts is built and maintained by one person, under GPL-3.0.