DeadLink Checker

Find broken links in markdown files - CLI + GUI in a single file

Features

• 🖥️ Dual Mode: CLI (with args) or GUI (no args) in one file
• 🔗 Local Links: Check relative file paths in markdown
• 🌐 Web URLs: Validate HTTP/HTTPS links with caching
• 📝 Wiki Links: Support for Obsidian-style [[links]]
• 🔄 Watch Mode: Continuous monitoring with auto-refresh
• 📤 Export: Save results to JSON/Markdown
• ⚡ Fast: Go version is 20x faster than Python

Quick Start

Python Version

# GUI mode (no arguments)
python3 dead_link_checker.py

# CLI mode
python3 dead_link_checker.py /path/to/markdown

# Check only web URLs
python3 dead_link_checker.py --web /path/to/markdown

# Watch mode (refresh every 5 seconds)
python3 dead_link_checker.py --interval 5s /path/to/markdown

Go Version (Recommended)

# Build
go build -o deadlink dead_link_checker.go

# GUI mode
./deadlink

# CLI mode
./deadlink /path/to/markdown

# Check only local file links
./deadlink --no-web /path/to/markdown

# Watch mode
./deadlink --interval 5s /path/to/docs

CLI Options

Flag	Description	Default
--web	Check web URLs	true
--no-web	Skip web URL checking	false
--file, --local	Check local file links	true
--no-file	Skip local file link checking	false
--timeout	HTTP timeout in seconds	10
--rate-limit	Rate limit between requests	0.1
--ignore	Regex patterns to ignore	-
--interval	Watch mode refresh interval (e.g., 5s)	-

Screenshots

GUI Mode

┌─────────────────────────────────────────────────────────┐
│                  Dead Link Checker                       │
├─────────────────────────────────────────────────────────┤
│ Directory: [/path/to/markdown    ] [Browse...]          │
│                                                         │
│ ☑ Check Web URLs  ☑ Check Local Links                  │
│                                                         │
│ [Start] [Stop] [Clear] [Export]                        │
│                                                         │
│ Progress: ████████████░░░░░░░░ 65% (130/200)           │
│ Checking: README.md                                     │
│                                                         │
│ ┌───────────────────────────────────────────────────┐  │
│ │ Results                                            │  │
│ │ SUMMARY                                            │  │
│ │ Total links: 150                                   │  │
│ │ Broken links: 5                                    │  │
│ └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

CLI Output

Scanning: /path/to/markdown
Mode: web=true, local=true

============================================================
SUMMARY
============================================================
Total links: 150
By type: {'local': 120, 'web': 25, 'anchor': 5}
By status: {'ok': 145, 'broken': 5}

⚠️  BROKEN LINKS (5):
------------------------------------------------------------
File                                     Line   Type     Status     URL
----------------------------------------------------------------------------------------------------
/Users/project/README.md                 42     local    broken     not_found: ./missing-file.md
/Users/project/docs/guide.md             18     web      broken     HTTP 404

Installation

Python

# Optional dependencies for better output
pip install httpx rich

Go

go get github.com/rivo/tview
go build -o deadlink dead_link_checker.go

Supported Link Types

Type	Example	Verified
Standard markdown	[text](url)	✅
Images		✅
Wiki/Obsidian	[[page]]	✅
HTML links	<a href="url">	✅
Reference links	[text][ref]	✅
Anchors	#section	⚠️ (not verified)

Performance

Metric	Python	Go
Startup	~200ms	~10ms
1000 files	~30s	~1.5s
Binary size	N/A	~12MB

Examples

Check a project for broken links

./deadlink /path/to/project

Continuous monitoring during editing

./deadlink --interval 10s /path/to/docs

Export results for CI/CD

./deadlink --no-web /path/to/project
# Results saved to dead_link_report.json

Project Structure

deadlink/
├── dead_link_checker.py      # Python version
├── dead_link_checker.go      # Go version
├── README.md                 # This file
└── LICENSE                   # MIT License

Why Two Versions?

• Python: Quick scripting, easy to modify, familiar to most developers
• Go: Single binary, 20x faster, no runtime dependencies, production-ready

Choose based on your needs - both have identical features!

Contributing

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Submit a PR

License

MIT License - see LICENSE for details.

Related Projects

• markdown-link-check - Node.js link checker
• lychee - Fast link checker in Rust
• muffet - Website link checker in Go

---

Made with ❤️ for maintaining clean documentation