Readability

Readability analyzes Markdown files and reports measures of reading difficulty, including grade level, reading ease, and estimated reading time based on 200 words per minute. It lists Flesch-Kincaid, Gunning Fog, Coleman-Liau, SMOG, and ARI grade-level scores, plus word and sentence metrics. It can detect or require MkDocs-style admonitions and produce results as a table, Markdown, JSON, summary, or report. Writers can set thresholds that cause CI checks to fail when content exceeds them, with path-specific settings in a .readability.yml file. The project documents a command-line tool, GitHub Action, Docker image, pre-commit hooks, and building from source; integrations and CI/CD examples include GitLab CI, CircleCI, and Jenkins. Its GitHub Action can add a formatted report to a workflow summary. Readability is free and MIT-licensed, with no paid plans listed. It runs on Linux, macOS, and Windows, though the documented Windows binary is amd64 only. Its scores assess word and sentence complexity, not accuracy, completeness, context, or tone.

Readability combines document-level scores with workflow checks and several output formats. It can flag complexity, but its scores do not judge whether content is accurate or complete.

It suits bloggers, technical writers, documentation teams, and students who want readability measures or automated content checks. Curious readers can also use its introductory material.

Readability is a free, open-source analyzer for Markdown files, built for writers and documentation teams that want measurable standards in their editing or delivery pipeline. It is a strong fit for technical content maintained in version control, less so for anyone expecting automatic rewrites or a judgment of editorial quality.

Overview

Readability combines multiple grade-level formulas with reading-ease, estimated reading time, and basic word and sentence statistics. That breadth helps teams compare drafts and monitor whether documentation is becoming denser. The scores remain signals about linguistic complexity: they cannot establish accuracy, completeness, context, or tone, so an editor still has to make the final call.

Key features

Scoring and checks

Reports include Flesch-Kincaid, Gunning Fog, Coleman-Liau, SMOG, and ARI grade-level scores, as well as reading ease and reading time calculated at 200 words per minute. Word and sentence metrics add useful diagnostics when a page feels unwieldy. MkDocs-style admonitions can be detected or required, which is valuable for documentation teams enforcing a house structure. There are no plain-language rewrites or accessibility recommendations, limiting its usefulness as a complete content-improvement assistant.

Thresholds and configuration

Configurable thresholds can fail a CI check when documentation exceeds chosen limits, turning readability policy into an enforceable quality gate. A .readability.yml file supports path-specific overrides, while a JSON Schema provides editor validation and autocomplete for configuration. This is a practical setup for repositories with different standards by directory, though it assumes maintainers are comfortable defining and managing those rules.

Outputs and automation

Table, Markdown, JSON, summary, and report outputs cover both human review and machine processing. The command-line tool, GitHub Action, Docker image, and pre-commit hooks let teams place checks where their workflow already runs. The GitHub Action can add a formatted report to an Actions job summary; documented CI examples also cover GitLab CI, CircleCI, and Jenkins. Docker guidance adds signed images, a signed SBOM, a distroless base, and non-root execution, with Cosign verification documented for security-conscious deployments.

Pricing

Readability costs free under its single Readability plan. The MIT-licensed GitHub Action, CLI, and Docker image are included, and no paid plans are listed. That makes it suitable for individual writers, students, and teams that can host their own checks without per-seat or usage fees. The trade-off is that there is no commercial tier offering rewrites, accessibility analysis, or managed service support.

Platforms

Readability runs on Linux, macOS, and Windows through documented deployment options including a Go command-line installation, Docker, GitHub Actions, pre-commit hooks, or a source build. Pre-built binaries cover Linux amd64 and arm64, macOS amd64 and arm64, and Windows amd64. Windows users on arm64 do not have a documented pre-built binary and would need another deployment route.

Who it's for

Bloggers, technical writers, documentation teams, students, and curious readers can use it to quantify complexity in Markdown. It is particularly well suited to repositories where thresholds, path-specific rules, and repeatable CI checks matter. It is a poor match for authors who need prose rewritten, accessibility advice, or evaluation of factual completeness and tone.

Pros and cons

• Pros: Five established grade-level formulas give a broader view than relying on one score.
• Pros: Threshold failures, pre-commit hooks, and CI integrations catch regressions before publication.
• Pros: JSON and other output modes work for both automation and editorial reporting.
• Pros: MIT licensing and free CLI, Action, and Docker distribution remove purchase and seat barriers.
• Cons: Scores measure complexity, not accuracy, completeness, context, or tone.
• Cons: No plain-language rewriting or accessibility guidance is provided.
• Cons: The documented Windows binary supports amd64 only.

Alternatives

Choose ToolsVale Readability Checker instead if you want a free option spanning Android, iOS, Linux, macOS, web, and Windows. Health Literacy Advisor is the better choice for a paid, health-focused workflow with a free trial and a $499-per-year English online license. For API-based use, APIVerve Website Readability API offers a freemium service with 200 monthly credits on its free tier, while ApyHub Readability Scores Documents API provides a 3,000-atom monthly free tier. Botoi Readability API suits developers seeking 1,000 requests per day at no cost; Oanor Readability API offers a free 2,340-call monthly tier. Pick textstat for a free, MIT-licensed Python package, or A2Z Tools Plain Language Analyzer for a free English-only web tool.

Verdict

Readability is the right recommendation for Markdown-based writing and documentation teams that need transparent, repeatable complexity checks in local and CI workflows at no cost. Choose something else when you need rewriting, accessibility direction, semantic quality review, or a hosted API rather than an open-source tool you integrate and maintain.