Lexi is a GitHub action that reports readability metrics for Markdown files in your pull requests. Use these metrics to help you understand how changes impact the readability of your documentation. Lexi reports an overall readability score that is calculated based on a scaled combination of the following readability metrics:
Reports describe the overall change to each file in a pull request, and also the impact the edits make to the documentation set as a whole.
Lexi displays a report for each commit. The scores displayed in the GitHub action represent the metrics from the most recent commit.
To view metrics from previous commits in a pull request:
Overall readability score: 20.18 (π’ +0.97)
File Readability README.md 22.36 (π’ +3.86) π’ - Shows an increase in readability π΄ - Shows a decrease in readability
File Readability FRE GF ARI CLI DCRS README.md 22.36 44.11 16.67 28.7 11.85 7.66 Β π’ +3.86 π’ +2.03 π’ +0.75 π’ +2.2 π΄ -0.7 π’ +0.01 Averages:
Β Readability FRE GF ARI CLI DCRS Average 20.18 14 16.94 19.17 15.11 9.52 Β π’ +0.97 π’ +0.51 π’ +0.19 π’ +0.55 π΄ -0.17 π’ +0
Metric Range Ideal score Flesch Reading Ease 100 (very easy read) to 0 (extremely difficult read) 60 Gunning Fog 6 (very easy read) to 17 (extremely difficult read) 8 or less Auto. Read. Index 6 (very easy read) to 14 (extremely difficult read) 8 or less Coleman Liau Index 6 (very easy read) to 17 (extremely difficult read) 8 or less Dale-Chall Readability 4.9 (very easy read) to 9.9 (extremely difficult read) 6.9 or less
Name | Necessity | Description |
---|---|---|
github-token |
Required | Use this token to post the report comment to pull requests. The GitHub Actions token can be used with ${{ secrets.GITHUB_TOKEN }} . |
glob |
Required | Use this pattern to match Markdown files you want to analyse. |
name: Report readability
# This action only works on pull request events
on: pull_request
jobs:
report-readability:
name: Report readability
runs-on: ubuntu-latest
steps:
- name: Checkout repo with history
uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: Rebilly/lexi@v2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
glob: '**/*.md'
command | description |
---|---|
test |
Run the unit tests. |
lint |
Run eslint on all files. |
format |
Run prettier on all files. |
build |
Build the dist file. You are required to run this locally in order to build the dist before opening a PR. |
run:local:report |
Run the action on two local folders, for testing and development. The first argument is the old ("base branch") folder and the sedcond argument is the new ("head branch") folder. For example yarn run:local:report ./test-data/old ./test-data/new . |
run:local:debugfile |
Display what the program parses from a single file, after stripping all non-wanted items from the file, and before rating the readability. For example yarn run:local:debugfile ./test-data/new/test-document.md . |
playground:dev |
Open the playground in local development mode for testing readability scores. |
When developing the action, it may be useful to run the action locally rather than pushing a branch and running your development version on GitHub.
To test the action locally, execute the run:local:report
command. This reports readability on two different directories, as though they are in one pull request.
For example: yarn run:local:report ./test-data/old ./test-data/new
main
branch.v
, for example v1.0.0
. v1.0.0
.To experiment with this tool in your web browser, and get real-time readability metric data as you edit a Markdown file, try out the playground.