broken-link-checker-cli
Check links in Markdown and HTML docs against real pages — and tell page failures apart from anchor failures.
What it does
broken-link-checker scans .md, .markdown, and .html files for links and checks each one for real:
- Local links: the target file must exist. If the link has an anchor, the target Markdown heading (GitHub-style slug) or HTML
id/namemust exist too. - Remote links: the URL must answer (HEAD, falling back to GET where a server refuses HEAD). If the link has an anchor, the fetched page must carry that
idorname. - Every result is one of three statuses, with the broken kind named:
BROKEN (page)for a missing page,BROKEN (anchor)for a page that exists without that anchor. A link is never reported OK unless its check actually ran. - Links inside fenced code blocks and inline code spans are ignored, so code samples never produce false failures.
- Exit code 0 means no broken links, 1 means at least one broken link, 2 means a usage error such as a missing path.
What it does NOT do
- It does not guess. If an anchor cannot be checked (for example, an anchor on a PDF), the link is reported
SKIPPEDwith the reason, never OK. - It does not check
mailto:,tel:, or other non-web schemes — those are reportedSKIPPED, not broken. - It does not follow JavaScript-rendered pages, log in to sites, or rewrite any file. It only reads and reports.
- It does not send your docs anywhere. Remote checks are plain requests to the linked URL itself; everything else runs locally.
Who it is for
Anyone who maintains docs, a README collection, or a static site and wants a broken link caught before a reader finds it — in CI, or as a one-off check before publishing.
Install
Python standard library only — no packages to download. Clone the repo and run it in place:
git clone https://github.com/haiderstudio/broken-link-checker-cli.git
cd broken-link-checker-cli
Usage
Check a directory (scanned recursively) or individual files:
python3 src/broken_link_checker.py docs/
python3 src/broken_link_checker.py README.md docs/guide.md
Real output from the bundled examples (one link is deliberately broken):
examples/sample-docs.md:3: other-page.md -> OK
examples/sample-docs.md:5: #sample-docs -> OK
examples/sample-docs.md:8: missing-page.md -> BROKEN (page) (file does not exist)
2 ok, 1 broken, 0 skipped
Useful flags:
# Skip remote checks entirely (local files only)
python3 src/broken_link_checker.py --local-only docs/
# Machine-readable output
python3 src/broken_link_checker.py --format json docs/
# Skip URLs matching a pattern (repeatable)
python3 src/broken_link_checker.py --exclude 'example\.com' docs/
Examples
Check only local links in a docs folder, so the run works offline:
python3 src/broken_link_checker.py --local-only docs/
Check one file and get JSON for a CI step:
python3 src/broken_link_checker.py --format json README.md
Run the bundled example (expect 2 ok, 1 broken, exit code 1):
sh examples/run-example.sh
How it is tested
python3 tests/test_broken_link_checker.py
The tests use only the standard library's unittest. Remote checks are exercised against a real HTTP server started by the tests on localhost — never against the public internet — covering a good page, a 404 page, a good anchor, and a missing anchor, plus local files, same-page anchors, skipped schemes, CLI exit codes, and JSON counts.
Contributing
Small, focused improvements are welcome. Open an issue first for anything larger than a typo, keep the standard-library-only rule, and run the tests before opening a pull request. See CONTRIBUTING.md.
Licence
MIT — see LICENSE. This is original work, built fresh for this repo.
Metadata
Release files for broken-link-checker-cli 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| broken_link_checker_cli-0.1.0.tar.gz | 9.0 kB | Without provenance | Details for broken_link_checker_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| broken_link_checker_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for broken_link_checker_cli-0.1.0-py3-none-any.whl |
Total release size: 16.7 kB
Release files / broken_link_checker_cli-0.1.0.tar.gz
| Download URL | broken_link_checker_cli-0.1.0.tar.gz |
|---|---|
| Size | 9.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f97d43c3834987191e24e88a2f730a6a2a97ec5deac095ffa7d5ac69da8c1ab
|
|
BLAKE2b-256 checksum How to use checksums |
b4ff4ecef851ce8f52a87d37bc139cd514e5c0a08d5db83cadd20a9f539ac399
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / broken_link_checker_cli-0.1.0-py3-none-any.whl
| Download URL | broken_link_checker_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 7.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e5e1672bf81a1ee9d83e786ebcbcf74cd0c6a0af068cd79d8095f69944a3e8de
|
|
BLAKE2b-256 checksum How to use checksums |
a2022e0ee6e2eea397570f7ec32e34bf9cc6e3bdd36ca53e92f44fce28c3024d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for broken-link-checker-cli 0.1.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.