Markdown docs linter for links, headings, alt text and code fences

What it does

Scans a documentation folder read-only and writes a report in Markdown or JSON.

• Broken relative links and images (Markdown, <img> and <a href>)
• Anchors that do not exist (GitHub-style heading slugs, including non-Latin headings)
• Reference links [text][label] without a definition, and unclosed code fences
• Heading level jumps (for example ## followed by ####), duplicate headings in a file, more than one H1
• Images without alt text, code fences without a language
• Very long lines (wide East Asian characters count as 2; tables, URL-only lines and code are skipped)

External URLs are never fetched, only counted. The exit code is 1 when errors exist, so it also works as a CI check.

How to use

python scripts/md_lint.py docs/ README.md --out md-lint.md
python scripts/md_lint.py docs/ --format json --disable long-line --max-line 100

The agent uses the report to find the correct path of moved files and the real target headings, proposes fixes, applies them only when asked and re-runs the check.

Requirements

• Python 3 (standard library only)

Caveats

• Some static site generators accept link styles that only work after build; treat those as needing confirmation.
• File names are case-sensitive on Linux servers.
• Complex HTML is not validated.
• No file edits and no network access.