# Dead Link Scanner

> Scan websites, markdown files, and HTML files for broken links (dead links). Use when checking a website for 404s, validating links in documentation or README files, auditing link health before a deploy, or finding broken internal/external links. Supports recursive crawling with depth limits, markdown file scanning, and output in text or JSON format.

- Skill: `dvcrn/dead-link-scanner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dvcrn/dead-link-scanner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/dead-link-scanner/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/dead-link-scanner

---


# dead-link-scanner

Find broken links in websites, markdown files, and HTML documents.

## Quick Start

```bash
# Scan a website for broken links
python3 scripts/dead_link_scanner.py scan https://example.com

# Scan with depth limit (default: 1)
python3 scripts/dead_link_scanner.py scan https://example.com --depth 3

# Scan a local markdown file
python3 scripts/dead_link_scanner.py file README.md

# Scan multiple files
python3 scripts/dead_link_scanner.py file docs/*.md

# JSON output
python3 scripts/dead_link_scanner.py scan https://example.com --json

# Only show broken links
python3 scripts/dead_link_scanner.py scan https://example.com --broken-only
```

## Commands

### `scan`
Crawl a website and check all links on each page.

```bash
python3 scripts/dead_link_scanner.py scan <url> [options]
```

Options:
- `--depth <n>` — Max crawl depth (default: 1, 0 = single page only)
- `--timeout <seconds>` — Request timeout (default: 10)
- `--json` — Output results as JSON
- `--broken-only` — Only show broken links
- `--internal-only` — Only check links within the same domain
- `--max-urls <n>` — Max URLs to check (default: 200)
- `--delay <seconds>` — Delay between requests (default: 0.2)

### `file`
Scan local markdown or HTML files for broken links.

```bash
python3 scripts/dead_link_scanner.py file <path>... [options]
```

Options:
- `--timeout <seconds>` — Request timeout (default: 10)
- `--json` — Output as JSON
- `--broken-only` — Only show broken links

## Output

Default text output:
```
✓ 200  https://example.com/about
✓ 200  https://example.com/blog
✗ 404  https://example.com/old-page  (found on: https://example.com)
✗ ERR  https://dead-domain.xyz  (found on: https://example.com) — ConnectionError
```

Summary line:
```
Checked 42 links: 39 OK, 3 broken
```