빠른 흐름

Markdown 링크 점검 순서

1. 로컬 상대 경로가 실제 파일을 가리키는지 확인
2. 같은 문서의 #anchor가 렌더러에서 생성되는 값과 맞는지 확인
3. 외부 URL은 상태 코드와 redirect를 확인
4. 이미지 링크는 파일 존재, 대소문자, 배포 경로를 확인
5. CI에서는 내부 링크와 외부 링크를 다른 강도로 검사

점검 범위

상대 링크는 파일 이동에 가장 자주 깨진다

상대 링크는 저장소 안에서 문서를 연결하기 좋지만, 파일을 옮기거나 디렉터리 이름을 바꾸면 바로 깨집니다. 문서 리팩터링에서는 본문 내용보다 링크 경로가 더 많이 망가질 수 있으므로, 이동 전후에 링크 점검을 따로 잡아야 합니다.

[설치 가이드](../setup/install.md)
![화면 예시](./images/screenshot.png)

Windows 개발 환경에서는 대소문자 차이가 드러나지 않을 수 있습니다. 배포 환경이 Linux라면 Images/logo.png와 images/logo.png는 다른 경로입니다.

섹션 링크는 제목 변경과 중복 제목에 취약하다

#설치-방법 같은 섹션 링크는 제목 텍스트에서 생성됩니다. 제목을 조금만 바꿔도 anchor가 바뀌고, 같은 제목이 반복되면 렌더러가 -1, -2 같은 접미사를 붙일 수 있습니다. 문서 내부 링크가 많은 문서는 제목 변경을 작은 수정으로 보면 안 됩니다.

본문의 설치 방법 섹션으로 이동합니다.
[설치 방법으로 이동](#설치-방법)

정적 사이트나 MDX 환경에서 명시적 anchor를 지원한다면, 오래 유지해야 하는 섹션에는 고정 ID를 쓰는 편이 안정적입니다.

외부 링크는 실패 기준을 분리한다

외부 URL은 일시 장애, bot 차단, redirect, 인증 필요 응답 때문에 CI에서 불안정할 수 있습니다. 내부 링크는 실패하면 빌드를 막고, 외부 링크는 주기적 리포트나 허용 목록을 두는 식으로 강도를 나누는 편이 실무적으로 안정적입니다.

강하게 실패시킬 항목
- 저장소 내부 상대 링크
- 이미지 경로
- 같은 문서 anchor

완화할 항목
- 외부 URL의 일시 429/5xx
- redirect가 잦은 문서 사이트
- 로그인 필요한 문서

자동화 기준

링크 점검 도구는 Markdown parser 기반이어야 합니다. 단순 문자열 검색은 code fence 안 예시 URL까지 검사하거나, 참조형 링크 정의를 놓칠 수 있습니다.

주의할 점

대규모 문서 저장소에서는 모든 외부 링크를 매 PR마다 검사하면 속도와 안정성이 떨어집니다. 내부 링크는 PR gate로 두고 외부 링크는 정기 작업으로 분리하는 방식이 유지 비용을 줄입니다.