| 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 파일 작성/수정 후 다음 세 가지를 반드시 검증합니다.
- 내부 파일 링크 (
[텍스트](경로.md)) — 파일 존재 여부
- 앵커 링크 (
#섹션명) — 실제 H2 섹션과 일치 여부
- 목차 완결성 — 실제 H2 섹션이 목차에 모두 포함되어 있는지
1. 앵커 링크 검사
GitHub 앵커 변환 규칙
헤딩 텍스트 → 앵커 변환 시 적용되는 규칙:
- 소문자 변환
- 영숫자·한글·공백·하이픈 이외 문자 제거 (특수문자 포함)
- 공백 →
- 변환 (연속 공백도 각각 -로, 축약 없음)
특수문자 제거로 인한 이중 하이픈 발생 예시:
| 헤딩 | 앵커 | 이유 |
|---|
컨텍스트 / 도구 상세 | #컨텍스트--도구-상세 | / 제거 → 양쪽 공백이 각각 - |
토큰 절약 & 성능 최적화 | #토큰-절약--성능-최적화 | & 제거 → 이중 하이픈 |
`@` 참조 기능 | #--참조-기능 | 백틱·@ 제거 → 앞 공백 - |
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 섹션(코드블록 밖)을 가리키는지 확인합니다.
검사 절차 (문서 작성/수정 후 필수)
- 코드블록 밖 H2 목록 추출
- 각 H2의 올바른 앵커 계산 (
github_anchor() 함수 사용)
- 목차의 모든 링크 앵커와 대조 → 불일치 시 수정
- 목차에 없는 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
수정 규칙
- 파일명 변경 반영 — 링크 텍스트와 경로 모두 수정
- 경로 누락 — 서브디렉토리 경로 추가
- 상대 경로 — 서브디렉토리에서 상위 참조 시
../ 사용
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 섹션을 추가/수정/삭제한 경우 반드시 확인합니다.
