errata-ai / readability

Vale-compatible implementations of many popular "readability" metrics.

Readability

This repository contains a Vale-compatible implementation of many popular "readability" metrics.

Getting Started

❗ Readability requires Vale >= 2.13.0. ❗

Download the latest release, copy the "Readability" directory to your StylesPath, and include it in your configuration file:

# This goes in a file named either `.vale.ini` or `_vale.ini`.
StylesPath = path/to/some/directory
MinAlertLevel = warning # suggestion, warning or error

# Only Markdown and .txt files; change to whatever you're using.
[*.{md,txt}]
# List of styles to load.
BasedOnStyles = Readability

See Usage for more information.

readability's Issues

Compilation error "unresolved reference" with empty files

I'm getting a compile error for empty files (or files with e.g. a table only) when using the readability metrics.

$ sw_vers
ProductName:            macOS
ProductVersion:         13.5.2
BuildVersion:           22G91
$ vale --version
vale version v2.29.1

Steps to reproduce:

$ cd testdata/ColemanLiau
$ touch empty.md
$ vale .
E201 Invalid value [/path/to/readability/Readability/ColemanLiau.yml:5:1]:

   4
   5* formula: |
   6    (0.0588 * (characters / words) * 100) - (0.296 * (sentences / words) * 100) - 15.8
   7

script run: Compile Error: unresolved reference 'characters'
        at (main):1:48

Execution stopped with code 1.

$ cd testdata/ColemanLiau
$ cat <<EOF > foo.md
| col1 | col2 |
|------|------|
| a    |      |
EOF
$ vale .
E201 Invalid value [/path/to/readability/Readability/ColemanLiau.yml:5:1]:

   4
   5* formula: |
   6    (0.0588 * (characters / words) * 100) - (0.296 * (sentences / words) * 100) - 15.8
   7

script run: Compile Error: unresolved reference 'characters'
        at (main):1:48

Execution stopped with code 1.

Erroneous Coleman-Liau Index message

The ColemanLiau definition specifies condition "> 9" but its message is "Try to keep the Coleman–Liau Index grade (%s) below 19".

Thus users can get a warnings such as "Try to keep the Coleman–Liau Index grade (10) below 19".

I suppose the condition is correct but the grade in the message is too high.

Unable to sync package

vale sync is unable to retrieve readability package

❯ vale --version
vale version 2.16.0
❯ cat ~/.vale.ini
StylesPath = .vale/styles
MinAlertLevel = suggestion

Packages = readability

[*]
BasedOnStyles = Vale, readability

❯ vale sync
Downloading packages [0/1] █     0% | 0sGet "readability": unsupported protocol scheme ""

I like SMOG score, but would it be possible to somehow show the pollysylabic words?

It is nice that I see “Try to keep the SMOG grade (10.36) below 10.”, but it would be nice to show all polysyllabic words which are the problem.

Configuration options to adjust the thresholds for readability rules

I'm trying out Vale for use on internal documentation, and I think the readability targets are hard to hit when the text needs to use standard technical terminology. For example, I'd like to be able to set the target for Readability.FleschReadingEase to 60 rather than 70 from my .vale.ini

Compile Error: unresolved reference 'NaN'

Using Readability 0.1.0, I am running into the following error:

$ cd .vale/styles && unzip Readability-0.1.0.zip
Archive:  Readability-0.1.0.zip
   creating: Readability/
  inflating: Readability/GunningFog.yml  
  inflating: Readability/FleschKincaid.yml  
  inflating: Readability/ColemanLiau.yml  
  inflating: Readability/AutomatedReadability.yml  
  inflating: Readability/LIX.yml     
  inflating: Readability/SMOG.yml    
  inflating: Readability/FleschReadingEase.yml  
  inflating: Readability/meta.json   
./bin/find.sh | xargs -0 vale --config .vale.ini --minAlertLevel warning --output=.vale/templates/cli.tmpl --no-wrap
E201 Invalid value provided [.vale/styles/Readability/ColemanLiau.yml:8:1]:

   7  
   8* condition: "> 9"

script run: Compile Error: unresolved reference 'NaN'
        at (main):1:37

Execution stopped with code 1.

Update files in Readabilty/ directory

If I understand the setup process correctly, the extends parameter in each .yml file requires a certain value.

Based on the current repo, when I run vale some.md file, I get the following error:

Invalid value provided [/Users/mike/Repos/cobalt-product-public-docs/styles/Readability/FleschKincaid.yml:1:10]:

   1* extends: metric
   2  message: "Try to keep the Flesch–Kincaid grade level (%s) below 8."
   3  link: https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests

'extends' key must be one of [capitalization conditional consistency existence occurrence repetition substitution readability spelling sequence].

I no longer get the error when I change metric to readability

Can't install Vale 2.13.0 using Chocolatey and no VS Code automatic check

When I run: choco upgrade vale it installs Vale v.2.10.0, not the latest Vale 2.13.0 required for readability check. Also, when I finally replaced vale.exe manually in the Chocolatey bin folder on Windows and tried to check the Markdown file in VS Code using the Vale extension, it doesn't show readability scores in the Problems tab. I had to run vale myfilename.md to see the PowerShell output for the readability.