init mdlink

README.md

@@ -0,0 +1,52 @@
+# 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
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install .
+```
+
+## Usage
+
+```bash
+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:
+
+```text
+Replace old URL with final URL? [y/N]
+```
+
+- [broken](https://httpbin.org/status/404)
+
+Only confirmed links are updated.
+
+## Help
+
+```bash
+mdlink --help
+```