Check markdown files for common issues including heading structure, link validity, list formatting, trailing whitespace, and code block language tags. Use when reviewing documentation, README files, or any .md file for consistency and best practices.
Documents
markdown-link-check
Try itScan markdown files and verify that all hyperlinks (both local files and remote URLs) resolve correctly. Use when you need to: (1) verify documentation before publishing, (2) check a repo README or wiki links, (3) audit markdown files for broken links before generating static sites or releasing content, (4) validate links in collected digital assets before archiving.
What it does
Scan markdown files and verify that all hyperlinks (both local files and remote URLs) resolve correctly. Use when you need to: (1) verify documentation before publishing, (2) check a repo README or wiki links, (3) audit markdown files for broken links before generating static sites or releasing content, (4) validate links in collected digital assets before archiving.
The skill document
Markdown Link Check
Scan one or many markdown files and report every broken hyperlink with line numbers and diagnostic reasons.
Quick Start
python3 scripts/check_links.py
Examples:
- Single file:
python3 scripts/check_links.py README.md - Whole directory:
python3 scripts/check_links.py ./docs --timeout 15 - Verbose mode (shows healthy links too):
python3 scripts/check_links.py . -v
What It Checks
| Link type | Behavior |
|---|---|
Remote URLs (http://, https://) | Sends HEAD request, reports HTTP status or connection error |
| Local relative paths | Verifies file exists relative to the markdown file's directory |
Anchors (#section) | Skipped (intra-file anchors are out of scope) |
Image links () | Skipped (use a dedicated asset checker for those) |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | All links resolved successfully |
| 1 | Broken links found (details printed to stdout) |
| 2 | File/directory argument invalid or unreadable |
Script Reference
scripts/check_links.py is a standalone Python 3 script with no external dependencies. It uses only the standard library (urllib, pathlib, concurrent.futures).
Key options:
--timeout N— HTTP timeout per request in seconds (default 10)-v, --verbose— Print healthy link summary in addition to broken ones
Related skills
Scan web files for broken hyperlinks and weak SEO anchor text, then interactively replace, strip, or skip each dead URL. Use when asked to find or fix broken...
3 installs
Markdown link auditor — find broken internal links, flag dead external links (HEAD requests), report orphan pages. Use when you maintain docs. Pure stdlib +...
4 installs
Scan a directory of Markdown files, extract titles/headings/frontmatter, build a searchable index JSON, and output a concise summary report. Use when you need to inventory, catalog, or make a folder of .md files discoverable without reading each file individually.
Generate and update table-of-contents (TOC) sections for Markdown files. Use when working with long Markdown documents, READMEs, or technical docs that need a navigable TOC, or when asked to add/update a table of contents in a .md file.
1 installs
Format and lint markdown files for consistency and readability. Use when Codex needs to normalize markdown documents, fix heading levels, standardize link fo...