retext-readability
retext plugin to check readability.
Contents
What is this?
This package is a unified (retext) plugin to check readability: whether your presumed target audience can read your prose. It applies Dale—Chall, Automated Readability, Coleman-Liau, Flesch, Gunning-Fog, SMOG, and Spache.
When should I use this?
You can opt-into this plugin when you’re dealing with content that might be difficult to read to some folks, and have authors that can fix that content.
💡 Tip: I also made an online, editable, demo, similar to this project:
wooorm.com/readability
.
Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with npm:
npm install retext-readability
In Deno with esm.sh
:
import retextReadability from 'https://esm.sh/retext-readability@7'
In browsers with esm.sh
:
<script type="module">
import retextReadability from 'https://esm.sh/retext-readability@7?bundle'
</script>
Use
Say our document example.txt
contains:
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 module example.js
looks as follows:
import {read} 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 = await unified()
.use(retextEnglish)
.use(retextReadability)
.use(retextStringify)
.process(await read('example.txt'))
console.error(reporter(file))
…now running node example.js
yields:
example.txt
3:1-5:57 warning Hard to read sentence (confidence: 4/7) retext-readability retext-readability
⚠ 1 warning
The target age is 16
by default, which you can change. For example, to 6
:
.use(retextEnglish)
- .use(retextReadability)
+ .use(retextReadability, {age: 6})
.use(retextStringify)
…now running node example.js
once moer 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
Configuration (optional).
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
).
Types
This package is fully typed with TypeScript. It exports the additional type Options
.
Compatibility
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.
Related
retext-syntax-mentions
— classify @mentions as syntaxretext-syntax-urls
— classify URLs and filepaths as syntaxretext-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.