마크다운 참고 링크가 글자로 남을 때: [안내][자료]와 정의 줄을 함께 확인
AI가 만든 마크다운에서 [안내][자료]가 링크 대신 그대로 보인다면, 문서에 맞는 정의 줄이 있는지 확인하세요. 참고 링크는 눈에 보이는 문구와 별도로 적은 라벨을 통해 목적지를 찾습니다.
아래 예시는 CommonMark 0.31.2를 기준으로 설명합니다. 실제 게시 서비스가 마크다운을 지원하는지, 어떤 문법을 적용하는지도 확인해야 합니다. 편집기에 글자를 붙였다는 사실만으로 클릭 가능한 링크가 저장됐다고 보지는 않습니다.
1. 표시 문구·라벨·목적지 세 부분
[배포 안내][release-note] [release-note]: https://example.com/releases
이 자체 예시에서 표시 문구는 “배포 안내”, 라벨은 “release-note”, 목적지는 예시용 주소입니다. 실제 작업에서는 존재하고 공개된 목적지로 바꾸세요. 정의 줄은 그 링크보다 앞이나 뒤에 둘 수 있고, 자체가 본문 문단으로 표시되는 요소는 아닙니다.
| 부분 | 점검할 질문 |
|---|---|
| 첫 대괄호 | 독자가 무슨 안내인지 알 수 있나 |
| 둘째 대괄호 | 정의 줄의 라벨과 맞나 |
| 정의 줄 | 콜론과 목적지가 있는가 |
| 공개 화면 | 실제 링크로 렌더링되고 이동하나 |
2. 복사 범위에서 정의가 빠지지 않았는지
본문 위쪽만 복사하고 문서 끝의 정의 줄을 빼면 참고 링크가 끊어질 수 있습니다. 원고를 나눠 옮길 때는 링크 사용 부분과 정의를 같은 게시 문서에 포함하세요.
정의 줄은 일반 문단을 중간에서 끊어 만들 수 없습니다. 실무에서는 앞 문단 다음에 빈 줄을 두고 정의를 따로 배치하면 검토하기 쉽습니다. 이 배치는 가독성을 위한 제안이며 모든 위치에서 빈 줄이 필수라는 뜻은 아닙니다.
3. 같은 라벨을 두 번 쓰면 첫 정의 확인
CommonMark는 일치하는 정의가 여러 개면 먼저 나온 정의를 사용합니다. 문서 끝에 새 주소만 추가했는데 링크가 계속 옛 주소로 간다면 앞쪽의 같은 라벨을 찾아보세요.
[일정][event] [event]: https://example.com/old [event]: https://example.com/new
이 자체 예시는 앞의 old 주소가 선택되는 중복을 보여 줍니다. 라벨의 대소문자 차이만으로 다른 목적지를 구분하려 하지 마세요. 필요한 목적지별로 의미 있는 다른 라벨을 쓰고 중복 정의를 정리합니다.
대괄호를 고쳤으면 끝인가요?
미리보기에서 표시 문구를 누르고 실제 목적지를 확인하세요. 렌더링 성공과 주소 정확성은 따로 점검할 항목입니다.
CommonMark 참고 링크 정의 규칙 읽기자료 확인: 2026년 10월 10일. CommonMark 0.31.2, 4.7·6.3
대표 썸네일은 이해를 돕기 위해 AI로 제작한 삽화입니다.
댓글
댓글 쓰기