Catch Broken Markdown Links and #Anchors Offline Before They Hit Production with DeadLinkFinder

Umut Güngör — Fri, 16 Oct 2026 10:57:38 +0000

Documentation rots quietly. You rename a file, refactor a section heading in your README.md, or move a diagram into a new folder—and suddenly your documentation is full of dead relative links and broken #heading-anchors.

Code review rarely catches these because nobody manually clicks every link and table-of-contents anchor in every pull request.

That is why I built DeadLinkFinder—a fast, zero-dependency Python CLI that verifies local Markdown links, image assets, GitHub-flavored heading anchors, and optional external URLs before they reach production.

Why Existing Link Checkers Frustrated Me

When I looked for a link linter for my repositories, I kept running into three problems:

Heavy runtime dependencies: Installing a full Node.js or headless browser stack just to check if ../docs/architecture.md exists in a Python repo felt unnecessary.
False positives on GitHub #anchors: GitHub's heading slug algorithm has specific rules around punctuation, Unicode characters, emojis, and duplicate headings (#install, #install-1). Naive regex checkers constantly fail on valid anchors.
Detection without diagnosis: Telling me "Target not found" is only half the job. If I made a typo in a 40-heading document, the tool should tell me what I probably meant.

Quick Start

DeadLinkFinder uses only the Python standard library (re, pathlib, difflib, urllib), meaning zero external dependencies to audit or maintain.

Install it directly from PyPI:

pip install deadlinkfinder

Run it against any directory or Markdown file:

deadlinkfinder docs/ README.md

Example terminal output:

$ deadlinkfinder docs/

🔍 DeadLinkFinder - Verifying documentation integrity...

[!] DLF-001  ERROR    docs/getting-started.md:28
    Target not found: '../guides/setup.md'
    Suggestion: Did you mean '../guides/install-setup.md'?

[!] DLF-002  ERROR    README.md:64
    Anchor not found: '#configuration-option'
    Suggestion: Did you mean '#configuration-options'?

Key Features Built for CI/CD

1. Offline-First with Fuzzy Suggestions (`difflib`)

By default, DeadLinkFinder runs 100% offline in milliseconds. It checks local file paths, image references (![alt](./assets/demo.png)), and cross-file anchors (./guide.md#installation). Whenever a target or anchor is missing, it uses difflib to suggest the closest existing file or heading slug.

2. GitHub-Compatible Heading Anchor Engine

Whether your headings contain Turkish characters, emojis, inline code backticks, or repeated section titles across a document, the anchor resolver mirrors GitHub's exact slug generation rules.

3. Native SARIF v2.1.0 & JSON Output

Want inline annotations directly on your GitHub Pull Requests or GitHub Code Scanning dashboard? Generate a SARIF report with deterministic line fingerprints:

deadlinkfinder . --format sarif --output results.sarif

Or use --format json for custom CI pipelines and pre-commit hooks.

Part of a Zero-Dependency CLI Suite

DeadLinkFinder is part of my open-source suite of zero-dependency developer tools, alongside EnvDoctor (for .env contract auditing) and TokenGuard (for pre-commit secret scanning).

Case Study & Architecture Notes: umutgungorr.com/projects/deadlinkfinder
Source Code (GitHub): github.com/umutgungorr/deadlinkfinder
PyPI Package: pypi.org/project/deadlinkfinder
More Engineering Articles & Projects: Umut Güngör — umutgungorr.com

If you maintain open-source documentation or internal engineering wikis, give deadlinkfinder a spin in your CI pipeline—feedback and issues are always welcome!

Stop Breaking Production: How to Audit and Sync .env Files with EnvDoctor

Umut Güngör — Thu, 15 Oct 2026 18:56:15 +0000

Every developer has been there: your code passes all local tests, you deploy to staging or production, and the application immediately crashes with KeyError: DATABASE_URL or an undefined environment variable.

As projects grow, maintaining .env files across different environments becomes painful:

.env.example drifts out of sync with actual code requirements.
New variables get added by teammates without documentation.
Secret leaks happen when templates aren't audited properly.

To solve this deterministically with zero bloat, I built EnvDoctor — a zero-dependency Python CLI tool designed to audit, synchronize, and validate environment configurations.

What Does EnvDoctor Do?

check: Compares your active .env against .env.example and flags missing or extraneous keys before you deploy.
sync: Safely merges new keys into .env.example without touching secrets or sensitive values.
audit: Scans your codebase with regex patterns to find environment variable calls that aren't declared in your documentation templates.

Example audit run:
$ envdoctor audit --strict
[PASS] .env matches .env.example
[WARN] Found undeclared variable in src/config.py: CACHE_TTL

Why Zero Dependencies?

CLI diagnostic tools should not add 50MB of third-party packages to your environment just to inspect text files. EnvDoctor relies entirely on the Python Standard Library, making it fast, secure, and instant to run in GitHub Actions or Docker entrypoints.

Links & Resources

GitHub Repository: github.com/umutgungorr/envdoctor
Author Portfolio & Systems: Umut Güngör (umutgungorr.com)
Deep Dive & Benchmarks: Read full case study on umutgungorr.com

Feel free to star the repo, test it on your projects, and share your feedback!

DEV Community: Umut Güngör