101 lines
2.3 KiB
Markdown
101 lines
2.3 KiB
Markdown
# 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 (``).
|
|
- 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
|
|
```
|
|
|
|
Scan current directory recursively:
|
|
|
|
```bash
|
|
mdlink .
|
|
```
|
|
|
|
## Options
|
|
|
|
- `--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:
|
|
|
|
- `scan_index`: already scanned files for incremental directory scans.
|
|
- `url_policy`: ignored URL decisions per file.
|
|
|
|
Single-file scans do not use state.
|
|
|
|
## Interactive Redirect Rewrite
|
|
|
|
Step 1: When a Markdown link redirects, `mdlink` prompts:
|
|
|
|
```text
|
|
Replace old URL? [y/N]
|
|
```
|
|
|
|
Step 2: For `http://` Markdown links without redirect, `mdlink` can test an `https://` variant and prompt:
|
|
|
|
```text
|
|
Replace old URL? [y/N]
|
|
```
|
|
|
|
Only confirmed links are updated.
|
|
|
|
## Test File And Script
|
|
|
|
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:
|
|
|
|
```bash
|
|
./test.sh
|
|
```
|
|
|
|
Generate test data only:
|
|
|
|
```bash
|
|
./test.sh --generate-only
|
|
```
|
|
|
|
Run the tool against generated test data:
|
|
|
|
```bash
|
|
mdlink testdata
|
|
```
|
|
|
|
## Help
|
|
|
|
```bash
|
|
mdlink --help
|
|
```
|