md-link-check

name	md-link-check
description	Validates markdown internal links, anchor links, and TOC completeness. Use after creating or modifying any .md file to verify link integrity and heading numbering.

Markdown Link & TOC Check Rules

목적

.md 파일 작성/수정 후 다음 세 가지를 반드시 검증합니다.

1. 내부 파일 링크 ([텍스트](경로.md)) — 파일 존재 여부
2. 앵커 링크 (#섹션명) — 실제 H2 섹션과 일치 여부
3. 목차 완결성 — 실제 H2 섹션이 목차에 모두 포함되어 있는지

---

1. 앵커 링크 검사

GitHub 앵커 변환 규칙

헤딩 텍스트 → 앵커 변환 시 적용되는 규칙:

1. 소문자 변환
2. 영숫자·한글·공백·하이픈 이외 문자 제거 (특수문자 포함)
3. 공백 → - 변환 (연속 공백도 각각 -로, 축약 없음)

특수문자 제거로 인한 이중 하이픈 발생 예시:

헤딩	앵커	이유
컨텍스트 / 도구 상세	#컨텍스트--도구-상세	/ 제거 → 양쪽 공백이 각각 -
토큰 절약 & 성능 최적화	#토큰-절약--성능-최적화	& 제거 → 이중 하이픈
`@` 참조 기능	#--참조-기능	백틱·@ 제거 → 앞 공백 -
Plan — 에이전트	#plan--에이전트	— 제거 → 이중 하이픈
CI/CD 비대화형	#cicd-비대화형	/ 제거, 양쪽 공백 없으면 단순 제거

앵커 검증 스크립트

import re

def github_anchor(heading):
    s = re.sub(r'^#+\s*', '', heading.strip())
    s = s.lower()
    s = re.sub(r'[^\w\s\-\uAC00-\uD7A3]', '', s)
    s = re.sub(r' ', '-', s)
    return s

코드블록 내부 헤딩 주의

``` 안의 ## 헤딩은 실제 섹션이 아닙니다. 목차 링크 대상은 코드블록 밖의 H2만 해당합니다.

---

2. 목차 완결성 검사

규칙

• 코드블록 밖의 모든 H2 섹션은 목차에 포함되어야 합니다.
• 단, 아래 고정 섹션은 목차에서 제외합니다: 목차, 참고 자료, 통계, 참고 URL
• 목차에 있는 링크가 실제 H2 섹션(코드블록 밖)을 가리키는지 확인합니다.

검사 절차 (문서 작성/수정 후 필수)

1. 코드블록 밖 H2 목록 추출
2. 각 H2의 올바른 앵커 계산 (github_anchor() 함수 사용)
3. 목차의 모든 링크 앵커와 대조 → 불일치 시 수정
4. 목차에 없는 H2 → 목차에 추가

---

3. 내부 파일 링크 검사

# 특정 파일의 내부 링크 검사
BASE=/path/to/repo
grep -oP '\[.*?\]\(\K[^)#]+\.md' FILE.md | while read link; do
  [ -f "$BASE/$link" ] && echo "OK  $link" || echo "❌  $link"
done

수정 규칙

1. 파일명 변경 반영 — 링크 텍스트와 경로 모두 수정
2. 경로 누락 — 서브디렉토리 경로 추가
3. 상대 경로 — 서브디렉토리에서 상위 참조 시 ../ 사용

---

4. H2 번호 체계

목차가 있는 문서의 H2 섹션은 번호를 부여합니다.

# ❌ 번호 없음
## 개요
## 설치
## 사용법

# ✅ 번호 있음
## 1. 개요
## 2. 설치
## 3. 사용법

번호 제외 대상

아래 섹션은 번호를 붙이지 않습니다.

섹션	이유
목차, 참고 자료, 통계	고정 푸터 섹션
문서 목록, 문서 트리	README 인덱스 구조
OS별/레이어별/연차별 분류 섹션	번호보다 분류 체계가 우선
단계 번호가 이미 있는 섹션 (1단계:, Phase 1 등)	중복 번호 방지

번호 불필요 문서 유형

아래 유형의 문서는 H2 전체에 번호를 붙이지 않습니다.

유형	예시
OS/버전별 분류 문서	root_password_recovery.md — CentOS 7, Rocky Linux 9 등
레이어/프로토콜별 분류	ddos_attacks_*.md — Layer 3, Layer 4, Layer 7
섹션명에 번호 포함	1단계:, 2단계:, Phase 1 등이 이미 섹션명에 있는 경우
비교/분석 문서	*_comparison.md, ansible_vs_jenkins.md
README 인덱스	문서 목록 나열이 주목적인 파일
영문 기능 목록	vim_airline.md 등 원문 유지 필요

번호 연속성

H2 번호는 1.부터 시작하여 빠짐없이 연속되어야 합니다. 번호 제외 대상 섹션은 카운트에서 제외합니다.

---

5. Bold 렌더링 깨짐 방지

**...(영문)**한글 패턴은 일부 마크다운 파서에서 닫힘 **를 인식하지 못해 bold가 깨집니다.

# ❌ 깨짐
**가상 테이블(Virtual Table)**이다.
**GC(Garbage Collection)**로 인한

# ✅ 정상 — ** 뒤 공백 1칸 추가
**가상 테이블(Virtual Table)** 이다.
**GC(Garbage Collection)** 로 인한

규칙: ** 닫힘 태그 바로 뒤에 한글이 오면 반드시 공백 1칸 삽입.

6. 문서 작성 후 체크리스트

문서를 새로 작성하거나 H2 섹션을 추가/수정/삭제한 경우 반드시 확인합니다.

• 모든 H2 헤딩의 앵커를 github_anchor() 규칙으로 계산했는가
• 목차의 모든 링크가 코드블록 밖 실제 H2를 가리키는가
• 코드블록 안의 ## 헤딩을 목차에 포함하지 않았는가
• 새로 추가한 H2 섹션을 목차에 추가했는가
• 코드블록 밖 H2 섹션에 1.부터 순차 번호가 붙어 있는가 (번호 제외 대상 섹션 제외)
• 특수문자(/, &, —, @, 백틱 등) 포함 헤딩의 앵커에 이중 하이픈(--)을 적용했는가
• **...(영문)**한글 패턴이 없는가 — 있으면 ** 뒤 공백 추가