Markdown RefCheck

Markdown RefCheck is a simple tool that checks Markdown references to find any broken links. It helps keeping your documentation free from broken section refs, missing images and files, and unavailable website links.

Features

• 🔍 Reference Detection — Validate links, images, file refs, and header anchors
• 🌐 Remote URL Checking — Validate external HTTP/HTTPS links (optional)
• 💬 Inline Ignore Comments — Suppress false positives with <!-- refcheck-ignore --> directives
• ⚙️ CI/CD Ready — Exit codes and --no-color for automation
• 🚀 Pre-commit Integration — Available as a pre-commit hook

Installation

pip install refcheck
# or
pipx install refcheck

Quick Start

# Check a single file
refcheck README.md

# Check a directory recursively
refcheck docs/

# Include remote URL validation
refcheck docs/ --check-remote

Example output:

$ refcheck README.md

[+] 1 Markdown files to check.
- README.md

[+] FILE: README.md...
README.md:3: #introduction - OK
README.md:5: #installation - OK
README.md:6: #getting-started - OK

Reference check complete.

============================| Summary |=============================
🎉 No broken references!
====================================================================

For all CLI options, see the CLI Reference.

Pre-commit

# .pre-commit-config.yaml
- repo: https://github.com/flumi3/refcheck
  rev: v0.6.2
  hooks:
    - id: refcheck
      args: ["docs/", "--exclude", "docs/filetoexclude.md"]

See the Integration Guide for CI/CD and other workflow setups.

Documentation

• CLI Reference — Command-line options
• Ignoring References — Suppress false positives
• Integration Guide — Pre-commit, CI/CD, Azure DevOps, Makefile
• Development Guide — Architecture, setup, conventions

Contributing

Contributions are welcome! See CONTRIBUTING.md.