Markdown RefCheck

Python

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  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.

Metadata

Release files for refcheck 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for refcheck 0.6.2
File	Size	Uploaded
refcheck-0.6.2.tar.gz	14.4 kB	Jun 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for refcheck 0.6.2
File	Interpreter	ABI	Platform	Reset
refcheck-0.6.2-py3-none-any.whl 15.9 kB Jun 30, 2026	Python 3	none	any	Details

Total release size: 30.3 kB

Release files / refcheck-0.6.2.tar.gz

Download URL	refcheck-0.6.2.tar.gz
Size	14.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`28aa5f68d9d5fc596e6493c12c495a11da307d51e6fd2a64d2937fade3aea094`
BLAKE2b-256 checksum How to use checksums	`8a30fdf8accf794fb0209acad0e99743a6a3149b25fa3e0e1cbf07d1cea19de8`
Upload date	Jun 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.8`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/flumi3/markdown-refcheck
Publishing commit: github.com/flumi3/markdown-refcheck/tree/125c712c683accdd44367210015db730d117eaa0

Workflow

Publishing configuration: github.com/flumi3/markdown-refcheck/blob/125c712c683accdd44367210015db730d117eaa0/.github/workflows/ci-cd.yml
Publishing logs: github.com/flumi3/markdown-refcheck/actions/runs/28447914422/attempts/1

Artifact

Subject: refcheck-0.6.2.tar.gz
SHA-256 checksum: 28aa5f68d9d5fc596e6493c12c495a11da307d51e6fd2a64d2937fade3aea094 Verifying attestations

Release files / refcheck-0.6.2-py3-none-any.whl

Download URL	refcheck-0.6.2-py3-none-any.whl
Size	15.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`28c83c2b769a765109da318d3ca78455728c67b94c0c68f93f52dc4bcd1df27f`
BLAKE2b-256 checksum How to use checksums	`8acd68dbbd50f73111837c1ee6fe6fa46bbb1a8ff672e212a037fc5c2363c59d`
Upload date	Jun 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.8`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/flumi3/markdown-refcheck
Publishing commit: github.com/flumi3/markdown-refcheck/tree/125c712c683accdd44367210015db730d117eaa0

Workflow

Publishing configuration: github.com/flumi3/markdown-refcheck/blob/125c712c683accdd44367210015db730d117eaa0/.github/workflows/ci-cd.yml
Publishing logs: github.com/flumi3/markdown-refcheck/actions/runs/28447914422/attempts/1

Artifact

Subject: refcheck-0.6.2-py3-none-any.whl
SHA-256 checksum: 28c83c2b769a765109da318d3ca78455728c67b94c0c68f93f52dc4bcd1df27f Verifying attestations