Skip to main content
The ls-metrics command analyzes a file and outputs various readability metrics and statistics as JSON.

​
Usage

vale ls-metrics <file>
​
file
string
required
Path to the file to analyze. The file must exist.
This command requires exactly one file argument. It does not accept multiple files or directories.

​
Output Format

The command outputs a JSON object containing computed metrics: 
{
  "paragraphs": 12,
  "sentences": 45,
  "words": 892,
  "characters": 4521,
  "syllables": 1247,
  "polysyllabicWords": 87,
  "reading_time": 4,
  "automated_readability_index": 9.2,
  "coleman_liau_index": 10.1,
  "flesch_kincaid_grade_level": 8.7,
  "flesch_reading_ease": 67.3,
  "gunning_fog": 10.5,
  "smog_index": 9.1,
  "linsear_write": 8.9
}

​
Metrics Explained

​
Basic Statistics

​
paragraphs
number
Number of paragraphs in the document.
​
sentences
number
Total sentence count.
​
words
number
Total word count, excluding punctuation.
​
characters
number
Total character count, including spaces.
​
syllables
number
Total syllable count across all words.
​
polysyllabicWords
number
Count of words with three or more syllables.
​
reading_time
number
Estimated reading time in minutes, based on average reading speed of 200 words per minute.

​
Readability Scores

Vale calculates several standard readability indices:
​
automated_readability_index
number
Automated Readability Index (ARI)Estimates the U.S. grade level needed to comprehend the text. Based on characters per word and words per sentence.
  • Lower scores (1-5): Elementary school
  • Middle scores (6-10): Middle/high school
  • Higher scores (11+): College level
​
coleman_liau_index
number
Coleman-Liau IndexEstimates U.S. grade level using character count instead of syllables.
  • Score of 8: Eighth grade reading level
  • Score of 12: High school senior reading level
​
flesch_kincaid_grade_level
number
Flesch-Kincaid Grade LevelTranslates the Flesch Reading Ease score into a U.S. school grade level.
  • Score of 6: Sixth grade level
  • Score of 10: Tenth grade level
  • Score of 13+: College level
​
flesch_reading_ease
number
Flesch Reading EaseRates text on a 100-point scale. Higher scores indicate easier readability.
  • 90-100: Very easy (5th grade)
  • 60-70: Standard (8th-9th grade)
  • 30-50: Difficult (College level)
  • 0-30: Very difficult (College graduate)
​
gunning_fog
number
Gunning Fog IndexEstimates years of formal education needed to understand the text.
  • Score of 8: Eighth grade level
  • Score of 12: High school senior level
  • Score of 17+: College graduate level
Based on sentence length and polysyllabic words.
​
smog_index
number
SMOG Index (Simple Measure of Gobbledygook)Estimates years of education needed to understand a piece of writing.
  • Score of 10: Tenth grade level
  • Score of 14: Undergraduate level
Particularly useful for technical writing.
​
linsear_write
number
Linsear Write FormulaDesigned specifically for technical writing. Calculates grade level based on easy and hard words.
  • Score below 8: Easy for students
  • Score of 8-11: Medium difficulty
  • Score above 11: Difficult

​
Examples

vale ls-metrics README.md

​
Use Cases

​
Verify Readability Goals

Check if content meets readability targets: 
FLESCH=$(vale ls-metrics document.md | jq '.flesch_reading_ease')
if (( $(echo "$FLESCH < 60" | bc -l) )); then
  echo "Warning: Text may be too difficult"
fi

​
Track Content Complexity

Monitor documentation complexity over time: 
vale ls-metrics docs/guide.md | jq '{
  words,
  flesch_reading_ease,
  reading_time
}'
Output: 
{
  "words": 1250,
  "flesch_reading_ease": 65.4,
  "reading_time": 6
}

​
Generate Reports

Create readability reports for multiple files: 
#!/bin/bash
echo "File,Words,Flesch,Grade Level"
for file in docs/**/*.md; do
  METRICS=$(vale ls-metrics "$file")
  WORDS=$(echo $METRICS | jq '.words')
  FLESCH=$(echo $METRICS | jq '.flesch_reading_ease')
  GRADE=$(echo $METRICS | jq '.flesch_kincaid_grade_level')
  echo "$file,$WORDS,$FLESCH,$GRADE"
done

​
CI/CD Integration

Enforce readability standards in continuous integration:
GitHub Actions
- name: Check readability
  run: |
    FLESCH=$(vale ls-metrics docs/readme.md | jq '.flesch_reading_ease')
    if (( $(echo "$FLESCH < 60" | bc -l) )); then
      echo "::error::Documentation readability score too low: $FLESCH"
      exit 1
    fi

​
How Metrics Are Calculated

1

Text extraction

Vale processes the file using a minimal configuration that extracts plain text while respecting markup structure.
2

Tokenization

The text is split into paragraphs, sentences, and words using linguistic rules.
3

Syllable counting

Vale uses an algorithm to estimate syllable counts for English words.
4

Score computation

Each readability formula is applied using the gathered statistics.
Metrics are calculated using a default .txt format configuration. For Markdown or other markup, Vale processes only the text content, excluding code blocks and similar elements.

​
Understanding Readability Scores

​
Target Scores by Audience

AudienceFlesch EaseGrade LevelFog Index
General public60-707-88-10
Technical docs50-609-1010-12
Academic30-5013+12+
Marketing60-806-88

​
Improving Scores

To improve readability metrics:
  • Shorten sentences - Break complex sentences into shorter ones
  • Use simpler words - Replace polysyllabic words with shorter alternatives
  • Reduce passive voice - Use active constructions
  • Add paragraphs - Break up long blocks of text
  • Vary sentence length - Mix short and medium sentences
Use the metrics as guidelines, not absolute rules. Technical documentation often requires complexity that results in lower readability scores.

​
Limitations

  • English only - Metrics are designed for English text and may not be accurate for other languages
  • Single file - The command processes only one file at a time
  • Estimation - Syllable counting and reading time are estimates
  • No context - Metrics don’t account for document purpose or audience expertise
  • lint - Lint files for style and grammar issues
  • ls-config - View configuration affecting metric calculation

Build docs developers (and LLMs) love

Get started for freeTalk to us