Markdown Link Checker -- local files, images, anchors, wikilinks

English | Japanese

---

Why mdlinkcheck?

Markdown repositories accumulate broken links over time: moved files, renamed headings, deleted images, and stale wikilinks. Existing link checkers focus on HTTP URL validation but ignore local file references, relative path resolution, image existence, and wikilink syntax used in tools like Obsidian.

mdlinkcheck scans your markdown and validates all link types from a single CLI:

Link Type	Example	Checked
Local files	[doc](guide.md)	Path exists, file readable
Images		Image file exists
Heading anchors	[see](#introduction)	Heading exists in target
Cross-file anchors	[see](doc.md#section)	Heading exists in target file
Wikilinks	[[other-note]]	File resolves with extension
Wikilink aliases	[[note|Display]]	File resolves
Wikilink anchors	[[note#heading]]	Heading exists

Install

pip install mdlinkcheck

Or install from source:

git clone https://github.com/izag8216/mdlinkcheck.git
cd mdlinkcheck
pip install -e .

Zero dependencies. Uses only Python standard library (3.10+).

Quick Start

# Scan a directory
mdlinkcheck scan ./docs

# Scan a single file
mdlinkcheck scan README.md

# Scan with anchor validation
mdlinkcheck scan ./docs --check-anchors

Commands

scan

Scan markdown files for broken links.

mdlinkcheck scan <path> [options]

Options:

Flag	Description
--check-anchors	Validate heading anchors (default: on)
--no-anchors	Skip heading anchor validation
--check-http	Perform HEAD checks on HTTP URLs (slow)
--no-images	Skip image reference checking
--no-wikilinks	Skip wikilink checking
--format text|json|github-actions	Output format
--exclude <patterns>	Glob patterns to exclude
--output <file>	Write output to file

Output Formats

text (default):

Found 2 broken link(s) in 3 file(s):

  docs/guide.md:12
    type:   local_file
    target: missing.md
    reason: File not found: missing.md

  docs/api.md:45
    type:   wikilink
    target: [[deleted-page]]
    reason: Wikilink target not found: deleted-page

json:

{
  "files_scanned": 3,
  "links_checked": 42,
  "broken_count": 2,
  "is_clean": false,
  "broken_links": [...]
}

github-actions (CI integration):

::warning file=docs/guide.md,line=12::[local_file] File not found: missing.md -- missing.md

CI Integration

Add to your GitHub Actions workflow:

- name: Check markdown links
  run: |
    pip install mdlinkcheck
    mdlinkcheck scan . --format github-actions

Obsidian Vault Support

mdlinkcheck validates [[wikilinks]] natively, making it ideal for Obsidian vaults:

mdlinkcheck scan ~/vault --check-anchors

It resolves wikilinks by trying .md, .markdown, and .txt extensions automatically.

Comparison

Feature	mdlinkcheck	markdown-link-check	lychee
Local file paths	Yes	No	Partial
Image references	Yes	HTTP only	HTTP only
Heading anchors	Yes	No	No
Wikilinks	Yes	No	No
HTTP URL checking	Optional	Yes	Yes
Zero dependencies	Yes	Node.js	Rust binary
Python native	Yes	No	No

License

MIT -- see LICENSE.