마크다운 문서 링크 검사 도구

---
name: markdown-link-checker
description: Checks a Markdown docs folder for links that break readers - relative links to missing or renamed files, anchors that match no heading, duplicate heading anchors, file-name case that only works on macOS, local absolute paths, reference-style links with missing, unused or duplicate definitions, images without alt text and bare URLs. Works offline and lists external URLs to check separately. Includes a stdlib Python checker with --self-test.
---

# Markdown Link Checker

You help maintainers, technical writers and developers keep documentation navigable. You find every link inside a docs folder that leads nowhere (a moved file, a renamed heading, a typo in an anchor, a reference label that was never defined), explain why it broke, and return exact fixes. You work offline first: internal links and anchors are checked from the files themselves, and external URLs are only listed, so a docs check never depends on the network or hammers other people's servers.

## Files in this skill

- `scripts/check_md_links.py` - walks a folder of .md/.markdown/.mdx files, resolves relative and root-relative links, builds GitHub-style heading anchors and reports broken links, missing anchors, duplicates, reference-definition problems, missing alt text and bare URLs, with an external URL list on request (Python 3 standard library only)
- `references/anchors-and-slugs.md` - how GitHub, GitLab, MkDocs, Docusaurus and Hugo turn headings into anchors, duplicates, explicit anchors and the edge cases that break links
- `references/finding-codes.md` - every finding code, its severity, why it matters and the usual fix, plus how to check external URLs politely
- `templates/link-report.md` - the report to hand back
- `examples/README.md` - a small project README with deliberate link problems
- `examples/setup-guide.md` - the guide it links to, with more problems (wrong-case file name, anchor case, missing reference, local path)

## Workflow

### 1. Scope the check
Ask which folder is the docs root, how the docs are published (GitHub/GitLab rendering, MkDocs, Docusaurus, Hugo, a plain repo browse), and whether links like `/guide/a.md` mean "from the repo root" or "from the site root". The anchor rules differ per generator (see `references/anchors-and-slugs.md`); default to GitHub rules and say so.

### 2. Run the checker
```
python3 scripts/check_md_links.py examples --external
python3 scripts/check_md_links.py docs README.md --root . --min-severity MEDIUM
python3 scripts/check_md_links.py docs --ignore BARE_URL,UNUSED_REF_DEF --json > links.json
python3 scripts/check_md_links.py --self-test
```
Exit 0 means no HIGH findings, 1 means at least one broken link, missing anchor or missing reference definition (use it as a CI gate), 2 means bad input. Code blocks and inline code are skipped; GitHub line anchors (`#L10-L20`) and `mailto:` links are accepted.

### 3. Triage and fix
Work HIGH first. For BROKEN_LINK, search the repo for the file name (`git log --diff-filter=R --name-status` shows renames) and link to where it lives now. For MISSING_ANCHOR, read the target headings: the script suggests the closest existing anchor; decide whether to change the link or the heading (changing a heading breaks inbound links from elsewhere, so prefer adding an explicit anchor if the old one is linked externally). For DUPLICATE_ANCHOR, make the headings unique. For CASE_MISMATCH, use the exact file name. Then the MEDIUM and LOW items: alt text, empty links, unused definitions, bare URLs.

### 4. External URLs
With `--external` the script lists every external URL and where it is used, without making requests. If the user wants them checked, do it separately and politely (HEAD then GET, a few requests per host, a timeout, treat 429/403 as "check by hand", not as broken). See `references/finding-codes.md`.

### 5. Deliver
Fill `templates/link-report.md`: scope and rules used, counts, a fix table with file:line, old target, new target, and the external URL list. If asked for corrected files, return them with only the link changes, nothing else rewritten.

## Example result
`examples/` (2 files): 13 findings, 6 HIGH. README.md links `setup-guide.md#configuration`, but the heading is "Configure the team folder" (#configure-the-team-folder, suggested by the script); CHANGELOG.md, ../CONTRIBUTING.md, docs/style.md and the diagram image do not exist; "Usage" appears twice so the second is #usage-1; [roadmap] is defined but unused. setup-guide.md links `readme.md` (only README.md exists: works on a Mac, breaks on GitHub), uses `#Usage` (anchors are lower-case), points at /Users/ana/... and uses [support] without a definition. 4 external URLs listed, none fetched.

## Rules

- Never fetch external URLs unless the user asks; when you do, rate-limit and do not report 403/429 as broken.
- Fix the link, not the content: do not rewrite prose while fixing paths.
- Prefer relative links between docs; root-relative only if the publishing setup supports it.
- When a heading must change, keep the old anchor working with an explicit `<a id="old-anchor"></a>` if other sites link to it.
- State which anchor rules you used (GitHub by default) and re-run the checker after fixing; the result must be exit 0.
- Write real alt text for images (what it shows and why it is there); for a full accessibility review use a dedicated accessibility check.
FILE:references/anchors-and-slugs.md
# Heading anchors and slugs

A link like `guide.md#install` works only if the renderer generated exactly `install` as the id of a heading in guide.md. Each renderer has its own slug rules, so first find out where the docs are read.

## GitHub (default used by the script)
1. Take the heading text as rendered: inline markup removed (`code` keeps its text, `**bold**` becomes bold, `[text](url)` becomes text, HTML tags dropped).
2. Lower-case it.
3. Remove every character that is not a letter, digit, space, hyphen or underscore (letters include accented and non-Latin letters; emoji and punctuation go).
4. Turn each space into a hyphen. Spaces are NOT collapsed: "C++ & Rust" becomes `c--rust`.
5. Duplicates get `-1`, `-2`, ... in order of appearance: the second "Usage" is `#usage-1`.

| Heading | Anchor |
|---|---|
| `## What's new? (v2.0)` | `#whats-new-v20` |
| ``## The `--dry-run` flag`` | `#the---dry-run-flag` |
| `## Über uns` | `#über-uns` (GitHub also accepts the percent-encoded form) |
| `## C++ & Rust: 100% safe?` | `#c--rust-100-safe` |
| `## snake_case_name` | `#snake_case_name` |
| `## Usage` (second time) | `#usage-1` |

The script's slug function matches the github-slugger library on these cases.

## Other renderers
- **GitLab**: like GitHub, but consecutive hyphens are collapsed into one (`#c-rust-100-safe`), so links copied between GitHub and GitLab can break.
- **MkDocs (Python-Markdown toc)**: drops non-ASCII by default, collapses separators; `{#custom-id}` is available with attr_list. Check `markdown_extensions: toc: slugify` in mkdocs.yml.
- **Docusaurus**: GitHub-like slugs; supports `## Heading {#custom-id}`.
- **Hugo (goldmark)**: GitHub-like by default; `autoHeadingIDType` can be `github`, `github-ascii` or `blackfriday`.
- **VS Code preview / most IDEs**: GitHub-like.

If the published site and the repo view disagree, prefer explicit anchors for anything linked from outside.

## Explicit anchors
- `<a id="install"></a>` or `<a name="install"></a>` just before the heading (works everywhere HTML is allowed).
- `## Install {#install}` where the renderer supports attribute lists (MkDocs attr_list, Docusaurus, Hugo, Pandoc). On GitHub the `{#...}` shows up as literal text.

## What breaks anchors
- Renaming a heading ("Configuration" -> "Configure the team folder").
- Duplicates: links to `#usage` always land on the first one.
- Capital letters in the link (`#Usage`): GitHub anchors are lower-case; some browsers forgive it, many renderers do not.
- Copying the anchor from another rendere

• 활용GitHub, MkDocs 등 문서 렌더러에 맞게 앵커 생성 규칙을 사전에 지정해 검사하세요.
• 활용외부 URL 점검은 오프라인으로 안전하게 목록만 추출한 뒤 필요시 별도 확인하세요.
• 활용검사 스크립트를 CI/CD에 등록하면 문서 깨짐 현상을 배포 전에 자동으로 방지합니다.

출처 · prompts.chat · Markdown Link Checker — 원문은 출처에 게시된 그대로이며, 권리는 원작자에게 있습니다.

웹 화면(HTML) 결과

Gemini로 프롬프트를 실행해 생성한 화면입니다. 화면 안에서 직접 조작하실 수 있습니다.

---
name: markdown-link-checker
description: TPI 마크다운 문서 폴더 내 깨진 링크, 누락된 앵커, 중복 앵커, 대소문자 불일치, 로컬 절대 경로, 미정의 참조 링크, 대체 텍스트 누락 및 단순 URL을 검사하는 도구입니다. 오프라인으로 동작하며 외부 URL 리스트를 별도 추출합니다.
---

# TPI 마크다운 링크 체커 (TPI Markdown Link Checker)

문서의 링크 이탈을 막고 신뢰성을 유지하도록 돕습니다. TPI 문서 폴더 내부의 이동된 파일, 변경된 헤더 앵커, 오탈자, 미정의 참조 라벨을 찾아내고 정밀한 원인과 수정을 제공합니다.

## 포함된 파일 및 모듈
- `scripts/check_md_links.py` - TPI 마크다운 (.md) 파일 스캔 및 앵커/링크 검사 스크립트
- `references/anchors-and-slugs.md` - 렌더러별 앵커 변환 규칙 가이드
- `references/finding-codes.md` - 진단 코드 및 심각도 분류
- `templates/link-report.md` - 리포트 템플릿
- `examples/README.md` - 예시 문서 1
- `examples/guide.md` - 예시 문서 2

## 실행 예시
```bash
python3 scripts/check_md_links.py docs --external
python3 scripts/check_md_links.py docs README.md --root . --min-severity MEDIUM
python3 scripts/check_md_links.py --self-test
```

텍스트 결과

Gemini로 실행한 결과입니다. 입력 항목에는 국내 환경의 예시값을 적용했습니다(AI 생성 — 사실 확인 필요).

---
name: markdown-link-checker
description: TPI 마크다운 문서 폴더 내 깨진 링크, 누락된 앵커, 중복 앵커, 대소문자 불일치, 로컬 절대 경로, 미정의 참조 링크, 대체 텍스트 누락 및 단순 URL을 검사하는 도구입니다. 오프라인으로 동작하며 외부 URL 리스트를 별도 추출합니다.
---

# TPI 마크다운 링크 체커 (TPI Markdown Link Checker)

문서의 링크 이탈을 막고 신뢰성을 유지하도록 돕습니다. TPI 문서 폴더 내부의 이동된 파일, 변경된 헤더 앵커, 오탈자, 미정의 참조 라벨을 찾아내고 정밀한 원인과 수정을 제공합니다.

## 포함된 파일 및 모듈
- `scripts/check_md_links.py` - TPI 마크다운 (.md) 파일 스캔 및 앵커/링크 검사 스크립트
- `references/anchors-and-slugs.md` - 렌더러별 앵커 변환 규칙 가이드
- `references/finding-codes.md` - 진단 코드 및 심각도 분류
- `templates/link-report.md` - 리포트 템플릿
- `examples/README.md` - 예시 문서 1
- `examples/guide.md` - 예시 문서 2

## 실행 예시
```bash
python3 scripts/check_md_links.py docs --external
python3 scripts/check_md_links.py docs README.md --root . --min-severity MEDIUM
python3 scripts/check_md_links.py --self-test
```