Skip to content

Quick Start

Run your first readability analysis and understand the results.

Your First Analysis

Point the tool at your documentation folder:

docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/adaptive-enforcement-lab/readability:latest /workspace/docs/

readability docs/

You'll see a table like this:

┌─────────────────────────┬───────┬─────────┬─────────┐
│ File                    │ Grade │ Flesch  │ Status  │
├─────────────────────────┼───────┼─────────┼─────────┤
│ docs/index.md           │ 8.2   │ 62.5    │ pass    │
│ docs/getting-started.md │ 10.1  │ 55.3    │ pass    │
│ docs/api-reference.md   │ 14.5  │ 38.2    │ fail    │
└─────────────────────────┴───────┴─────────┴─────────┘

Understanding the Scores

  • Grade: School grade level needed (lower is simpler)
  • Flesch: Reading ease score (higher is easier)
  • Status: Pass/fail based on your thresholds

Output Formats

  • Table

    readability docs/

    Human-readable format for terminal viewing.

  • Markdown

    readability -f markdown docs/

    Perfect for GitHub PR summaries and comments.

  • JSON

    readability -f json docs/

    Structured output for scripts and automation.

  • Diagnostic

    readability -f diagnostic docs/

    LSP-compatible format for IDE integration.

Check Mode

Add --check to fail when thresholds are exceeded. This is useful for CI pipelines.

docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/adaptive-enforcement-lab/readability:latest \
  --check /workspace/docs/

readability --check docs/

The command exits with code 1 if any file fails. Use this in your CI to block PRs with readability issues.

Custom Thresholds

Override defaults from the command line:

docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/adaptive-enforcement-lab/readability:latest \
  --check --max-grade 12 --max-ari 12 /workspace/docs/

readability --check --max-grade 12 --max-ari 12 docs/

Or create a .readability.yml file for persistent settings:

thresholds:
  max_grade: 12
  max_ari: 12
  max_lines: 400
  min_admonitions: 1

Config File Location

Place .readability.yml in your repository root. The tool finds it automatically.

When using Docker, the config file is automatically detected when you mount your workspace with -v "$(pwd):/workspace".

What's Next?