mdlink

mdlink is a CLI tool to recursively scan Markdown files and validate HTTP/HTTPS links.

Features

• 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

Options

• --timeout FLOAT
  Per-request timeout in seconds (default: 10.0).

Interactive Redirect Rewrite

When a Markdown link redirects, mdlink prompts:

Replace old URL with final URL? [y/N]

• broken

Only confirmed links are updated.

Help

mdlink --help