Scans .md files recursively in a directory (or a single .md file).
Extracts Markdown links ([text](url)) and naked URLs (https://...).
Ignores image links (![alt](url)).
Checks links with httpx and follows redirects automatically.
Ignores 200 OK in the report; shows non-200 and request errors.
Shows final resolved URL in output.
Asks interactively before rewriting redirected Markdown links.
Re-checks target URL before writing (must still return 200).
Rewrites links via Markdown AST editing (markdown-it-py), not string replacement.

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install .

Usage

mdlink /path/to/docs

Scan current directory recursively:

mdlink .

--timeout FLOAT
Per-request timeout in seconds (default: 10.0).
--rescan
Reset only scan_index in .mdlink-state.json and run a full scan on all matching files.
--reset-url-policy
Clear all stored URL ignore policies before scanning.
--check CODE
Report only selected HTTP status codes. Repeat option for multiple codes (for example --check 404 or --check 301 --check 404).

By default, mdlink stores:

Single-file scans do not use state.

Step 1: When a Markdown link redirects, mdlink prompts:

Replace old URL? [y/N]

Step 2: For http:// Markdown links without redirect, mdlink can test an https:// variant and prompt:

Replace old URL? [y/N]

Only confirmed links are updated.

This repository includes:

test.sh: Generates three sample Markdown files in testdata/ and runs state-related checks.
testdata/*.markdown: Sample files with mixed link cases (200, redirect, 404/500, naked URLs, ignored image/non-http links).

Generate test data and run checks:

./test.sh

Generate test data only:

./test.sh --generate-only

Run the tool against generated test data:

mdlink testdata

mdlink --help