ci: catch broken markdown links

[x-n2o]

Proposed changes

Adds a markdown link check to the existing pre-commit workflow so repository-local links are validated locally and in pull request CI. Per review feedback, this now uses a small local script (support/check_links.py, adapted from the one suggested in review) instead of a third-party dependency.

• pre-commit passes the tracked markdown files to the script; links with a URL scheme or host are skipped — matching the previous offline lychee behavior without the extra dependency. The script also supports a manual whole-tree scan: python3 support/check_links.py .
• Links inside fenced code blocks are ignored.
• Link targets that no longer live in this repository are not treated as broken: targets resolving outside the checkout are skipped, and a .check-links-ignore blocklist (fnmatch globs, repo-root relative) covers prompt fixtures (Applications/LLMEval/Models/*) and the paths that moved to the mlx-swift-lm package (Libraries/MLXLLM/*, Libraries/Embedders/*).
• The same script is proposed for mlx-swift in ci: catch broken markdown links mlx-swift#403; the two copies are kept in sync.

This helps prevent broken repository links like the missing Tools/image-tool/README.md entry reported in #477 (fixed by #481).

The one genuinely broken in-repo link surfaced by the check is tracked separately:

• [BUG] mnist-tool README links to missing MNIST documentation #484 — Tools/mnist-tool/README.md → Libraries/MNIST/README.md, renamed to MLXMNIST in add VLM support, refactor common LM code into MLXLMCommon. breaking API changes #151 (fixed by docs(mnist-tool): fix link to renamed MLXMNIST README #485)

Checklist

Put an x in the boxes that apply.

• I have read the CONTRIBUTING document
• I have run pre-commit run --all-files to format my code / installed pre-commit prior to committing changes
• I have added tests that prove my fix is effective or that my feature works
• I have updated the necessary documentation (if needed)

Local run — the check correctly flags the link tracked in #484; once #485 lands this goes green:

❯ pre-commit run --all
swift-format.............................................................Passed
check markdown links.....................................................Failed
- hook id: check-markdown-links
- exit code: 1

Tools/mnist-tool/README.md:
  line 3: [MNIST README.md](../../Libraries/MNIST/README.md) -> NOT FOUND

Total: 1 broken link(s) in 1 file(s)

[Copilot]

Pull request overview

This PR adds repository-local Markdown link validation by integrating the lychee link checker into the existing pre-commit workflow and ensuring it runs in pull request CI, helping prevent broken intra-repo documentation links (e.g., the missing Tools/image-tool/README.md link reported in #477).

Changes:

• Add a lychee pre-commit hook (offline mode) to validate Markdown links without external network access.
• Update the PR CI workflow step labeling/messaging to reflect link checks alongside style checks.
• Add contributor acknowledgment for the CI/link-check addition.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
ACKNOWLEDGMENTS.md	Adds a new contributor entry related to link-checking changes.
.pre-commit-config.yaml	Adds a lychee hook to check Markdown links (offline) as part of pre-commit/CI.
.github/workflows/pull_request.yml	Updates lint job step name/message to include Markdown link checks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[x-n2o]

Issues found in 4 inputs. Find details below.
[ERROR] file:///Users/ledio/src/mlx-swift-examples/Libraries/MLXLLM/LLMModelFactory.swift#L78 (at 28:41) | File not found. Check if file exists and path is correct
[ERROR] file:///Users/ledio/src/mlx-swift-examples/Tools/image-tool/README.md (at 32:3) | File not found. Check if file exists and path is correct
[ERROR] file:///Users/ledio/src/mlx-swift-examples/Libraries/Embedders/README.md (at 5:3) | File not found. Check
[ERROR] file:///Users/ledio/src/mlx-swift-examples/Libraries/MNIST/README.md (at 3:9) | File not found. Check if file exists and path is correct

@copilot open issues for all 4 broken links above using https://github.com/ml-explore/mlx-swift-examples/blob/main/.github/ISSUE_TEMPLATE/bug_report.md

[davidkoski]

I like the idea, but I wonder if we can just do it with a local tool instead of a 3rd party dependency? I had claude throw something together:

check_links.py

Is there something lychee gives that is missing here (especially in offline mode)?

[x-n2o]

No it was just convenient and when Claude reinvented the wheel for me the regex was a bit unreadable. I totally understand the reluctance of relying on a third party tool though, especially from a security POV - hence the pinned version.

[x-n2o]

I like the idea, but I wonder if we can just do it with a local tool instead of a 3rd party dependency? I had claude throw something together:

check_links.py

Is there something lychee gives that is missing here (especially in offline mode)?

@davidkoski updated PR to use local check_links.py - reused in ml-explore/mlx-swift#403 as well

[x-n2o]

@copilot review PR again please

[davidkoski]

Hah, it caught the issue in #485. I merged that so if you rebase this should run clean.

[davidkoski]

once we get this set up, it would be great to have this in all the mlx-swift repos!

[davidkoski]

@x-n2o OK, I think the issues that this detects are now fixed on main -- can you rebase and I will run CI again?

[dkoski@dkoski-m5 mlx-swift-examples (markdown-link-check)]$ ./support/check_links.py .
No broken links found.

Thanks!

[davidkoski]

Now just failing on:

Tools/mnist-tool/README.md:
  line 3: [MNIST README.md](../../Libraries/MNIST/README.md) -> NOT FOUND

MNIST -> MLXMNIST