mdref

A fast, Rust-based tool for discovering and migrating Markdown references — it processed 155 directories and 1,561 files in just 0.2 seconds. Support search by file or directory.

Caution

This project is still in early development, and some features may not be fully functional. Please use it with caution and report any issues you encounter.

Basic Usage

Install & Update

Install prebuilt binaries via shell script：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/studentweis/mdref/releases/download/0.4.4/mdref-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://github.com/studentweis/mdref/releases/download/0.4.4/mdref-installer.ps1 | iex"

Update mdref:

mdref-update

Basic command

• find 🔍：Find all markdown references in the specified directory.
• mv 🔥：Move file and update markdown references.
• rename 🔄：Rename file and update markdown references.

Commands that need directory scanning respect standard ignore rules such as .gitignore, so ignored Markdown files under directories like .git, node_modules, and target are skipped during reference discovery and rewrite planning.

$ mdref find ./examples/main.md

References to ./examples/main.md:
./examples/inner/sub/other.md:3:1 - ../../main.md
./examples/other.md:7:1 - main.md
./examples/inner/other.md:3:1 - ../main.md
./examples/main.md:7:1 - main.md
./examples/inner/sub/main.md:3:1 - ../../main.md
./examples/inner/main.md:3:1 - ../main.md
Links in ./examples/main.md:
./examples/main.md:3:2 - main.jpg
./examples/main.md:5:2 - main.jpg
./examples/main.md:7:1 - main.md
./examples/main.md:7:25 - inner/main.md
./examples/main.md:7:55 - inner/sub/main.md
./examples/main.md:9:1 - other.md
./examples/main.md:9:27 - inner/other.md
./examples/main.md:9:59 - inner/sub/other.md

For CI/CD or other automation, use JSON output:

$ mdref find ./examples/main.md --format json
{
	"operation": "find",
	"target": "./examples/main.md",
	"references": [
		{
			"path": "./examples/other.md",
			"line": 7,
			"column": 1,
			"link_text": "main.md"
		}
	],
	"links": [
		{
			"path": "./examples/main.md",
			"line": 7,
			"column": 1,
			"link_text": "main.md"
		}
	]
}

The same --format json flag is available on mv and rename. Successful responses include the resolved destination, dry_run, and the planned or applied line replacements. Failures return JSON on stderr with the command context and error message.

Contributing

If you want to submit code to this repository, please first refer to CONTRIBUTING.

Thanks for your help!