markdown-checker 1.2.0

A markdown link validation reporting tool.

markdown-checker is a markdown link validation reporting tool for .md and .ipynb files. It flags broken relative paths, broken web URLs, missing locale segments, and missing tracking IDs, then writes the findings as a report your CI can post back to a pull request.

Features

• Five built-in checks: broken relative paths, broken web URLs, locale segments in URLs, and tracking IDs on URLs and paths.
• Concurrent URL checking with cross-file deduplication, per-host rate pacing, and Retry-After/429 handling, so large repositories don't trip host rate limits.
• Four report formats: markdown, json, github-annotations, and console.
• Error vs. warning severity - rate-limited or unverifiable links are reported but never fail your CI.
• Configuration via a [tool.markdown-checker] table in pyproject.toml, so you don't have to repeat flags in every command or workflow file.

Installation

pip install markdown-checker

Quickstart

markdown-checker . -f check_broken_paths

🔍 Checked 42 links in 10 files.
All files are compliant with the guidelines. 🎉

When issues are found, a comment.md report is written and the command exits with a non-zero status:

🔍 Checked 42 links in 10 files.
😭 Found 1 issues in the following files:
    File 'docs/index.md', line 5
./missing.md is broken.

Using markdown-checker in GitHub Actions

Run this tool within a GitHub workflow using the action-check-markdown GitHub Action, which posts the report as a pull request comment:

- uses: john0isaac/action-check-markdown@v1.1.0
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    command: check_broken_paths
    directory: ./
    guide-url: "https://github.com/<owner>/<repo>/blob/main/CONTRIBUTING.md"

See the GitHub Actions how-to for the full workflow, including running check_broken_urls (not yet supported by the wrapper action) directly as a step.

Documentation

• Tutorial - install and run your first check.
• How-to guides - configuration, rate limiting, report formats, CI.
• CLI reference - every command-line option.
• API reference - for programmatic use.
• Full documentation.

Contributing

Contributions are welcome - see the Contributing guide.

License

MIT