check_markdown_links Namespace Reference

Functions
	iter_markdown_files (Path repo_root)
bool	should_skip_link (str target)
str	normalize_target (str raw_target)
int	main ()

Variables
	LINK_PATTERN = re.compile(r"!\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)|\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)")

Detailed Description

Basic local markdown link checker for README + authored docs pages.

Function Documentation

iter_markdown_files()

check_markdown_links.iter_markdown_files

(

Path

repo_root

)

Definition at line 12 of file check_markdown_links.py.

def iter_markdown_files(repo_root: Path):
    yield repo_root / "README.md"
    for md in sorted((repo_root / "docs").rglob("*.md")):
        if "docs_build" in md.parts:
            continue
        yield md
 
 

Here is the caller graph for this function:

should_skip_link()

bool check_markdown_links.should_skip_link

(

str

target

)

Definition at line 20 of file check_markdown_links.py.

def should_skip_link(target: str) -> bool:
    lower = target.lower()
    return (
        lower.startswith("http://")
        or lower.startswith("https://")
        or lower.startswith("mailto:")
        or lower.startswith("#")
    )
 
 

Here is the caller graph for this function:

normalize_target()

str check_markdown_links.normalize_target

(

str

raw_target

)

Definition at line 30 of file check_markdown_links.py.

def normalize_target(raw_target: str) -> str:
    cleaned = raw_target.strip().strip("<>").split("#", 1)[0].split("?", 1)[0]
    return cleaned
 
 

Here is the caller graph for this function:

main()

int check_markdown_links.main

(

)

Definition at line 35 of file check_markdown_links.py.

def main() -> int:
    repo_root = Path(__file__).resolve().parents[1]
    failures = []
 
    for md_file in iter_markdown_files(repo_root):
        if not md_file.is_file():
            failures.append((str(md_file), "<file>", "Markdown file not found"))
            continue
        content = md_file.read_text(encoding="utf-8", errors="replace")
        for match in LINK_PATTERN.findall(content):
            target = match[0] or match[1]
            if should_skip_link(target):
                continue
            normalized = normalize_target(target)
            if not normalized:
                continue
            resolved = (md_file.parent / normalized).resolve()
            if not resolved.exists():
                failures.append((str(md_file.relative_to(repo_root)), target, str(resolved)))
 
    if failures:
        print("Broken markdown links detected:")
        for src, target, resolved in failures:
            print(f"  - {src}: '{target}' -> missing '{resolved}'")
        return 1
 
    print("Markdown link check passed for README.md and docs/**/*.md")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

LINK_PATTERN

check_markdown_links.LINK_PATTERN = re.compile(r"!\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)|\[[^\]]*\]\‍(([^)\s]+)(?:\s+\"[^\"]*\")?\‍)")

Definition at line 9 of file check_markdown_links.py.