retext-readability

retext plugin to check readability. Applies Dale—Chall, Automated Readability, Coleman-Liau, Flesch, Gunning-Fog, SMOG, and Spache.

Tip: I also made an online editable demo, similar to this project: wooorm.com/readability.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install retext-readability

Use

Say we have the following file, example.txt:

The cat sat on the mat

The constellation also contains an isolated neutron
star—Calvera—and H1504+65, the hottest white dwarf yet
discovered, with a surface temperature of 200,000 kelvin

…and our script, example.js, looks like this:

import {readSync} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import {unified} from 'unified'
import retextEnglish from 'retext-english'
import retextStringify from 'retext-stringify'
import retextReadability from 'retext-readability'

const file = readSync('example.txt')

unified()
  .use(retextEnglish)
  .use(retextReadability)
  .use(retextStringify)
  .process(file)
  .then((file) => {
    console.error(reporter(file))
  })

Now, running node example yields:

example.txt
  3:1-5:57  warning  Hard to read sentence (confidence: 4/7)  retext-readability  retext-readability

⚠ 1 warning

By default, the target age is 16, but ages can be set, for example, to 6:

   .use(retextEnglish)
-  .use(retextReadability)
+  .use(retextReadability, {age: 6})
   .use(retextStringify)

Now, running node example once more yields:

example.txt
  1:1-1:23  warning  Hard to read sentence (confidence: 4/7)  retext-readability  retext-readability
  3:1-5:57  warning  Hard to read sentence (confidence: 7/7)  retext-readability  retext-readability

⚠ 2 warnings

API

This package exports no identifiers. The default export is retextReadability.

unified().use(retextReadability[, options])

Detect possibly hard to read sentences.

options.age

Target age group (number, default: 16). Note that the different algorithms provide varying results, so your milage may vary with people actually that age. 😉

options.threshold

Number of algorithms that need to agree (number, default: 4 / 7) By default, 4 out of the 7 algorithms need to agree that a sentence is hard to read for the target age, in which case it’s warned about.

options.minWords

Minimum number of words a sentence should have when warning (number, default: 5). Most algorithms are designed to take a large sample of sentences to detect the body’s reading level. This plugin works on a per-sentence basis and that makes the results quite skewered when a short sentence has a few long words or some unknown ones.

Messages

Each message is emitted as a VFileMessage on file, with the following fields:

message.source

Name of this plugin ('retext-readability').

message.ruleId

Name of this rule ('readability').

message.actual

Current not ok sentence (string).

message.expected

Empty array as there is no direct fix for actual ([]).

message.confidence

Number between 0 and 1 to represent how many algorithms agreed (number).

message.confidenceLabel

String representing the fraction of confidence (string, such as 4/7).

Related

• retext-syntax-mentions — Classify @mentions as syntax
• retext-syntax-urls — Classify URLs and filepaths as syntax
• retext-simplify — Check phrases for simpler alternatives

Contribute

See contributing.md in retextjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer