숏컷 코드

[공식 문서][docs]
[API 문서][docs]

[docs]: https://example.com "선택적 툴팁"

문법

참조형 링크는 URL을 본문에서 분리해 가독성과 유지보수성을 동시에 높인다

인라인 링크 [텍스트](https://very-long-url.com/path/to/resource) 는 URL이 길어질수록 소스 가독성이 떨어진다. 참조형 링크는 본문에서 [텍스트][id]처럼 짧은 식별자만 쓰고, 실제 URL은 문서 하단에 [id]: https://... 형식으로 모아 두는 방식이다. 이 분리 덕분에 본문 줄 길이가 짧아져 소스 파일의 diff 리뷰가 쉬워지고, URL을 한 곳에서 수정할 수 있어 유지보수 비용이 줄어든다.

자세한 설명은 [설치 가이드][install]를 보고,
명령어 목록은 [CLI 문서][cli]와 함께 확인합니다.

[install]: https://example.com/install
[cli]: https://example.com/cli

같은 식별자를 여러 번 쓰면 URL 변경이 한 곳에서 끝난다

참조형 링크의 가장 강력한 장점은 같은 URL을 본문에서 반복해서 참조할 때 나타난다. 인라인 방식에서는 URL이 바뀌면 모든 등장 지점을 찾아 수정해야 하지만, 참조형에서는 링크 정의 한 줄만 바꾸면 전체 문서에 반영된다. URL이 자주 바뀌는 외부 자원이나 내부 문서 경로에 특히 유리하다.

[공식 문서][docs]를 먼저 확인하고,
문제가 있으면 [공식 문서][docs] FAQ 섹션을 참고합니다.
버전 별 변경사항도 [공식 문서][docs]의 변경 로그에서 볼 수 있습니다.

[docs]: https://example.com/docs
<!-- URL이 바뀌어도 이 한 줄만 수정 -->

링크 정의는 문서 어디에나 둘 수 있지만 위치 규칙을 팀 내에서 통일해야 한다

CommonMark 기준으로 링크 정의([id]: url)는 문서 어느 위치에 있어도 인식된다. 관행적으로 문서 맨 하단에 모아 두거나, 참조하는 섹션 바로 아래에 두는 두 가지 스타일이 있다. 하단 집중 방식은 전체 링크를 한눈에 보기 쉽고, 섹션별 배치 방식은 해당 섹션을 복사해도 링크 정의가 함께 따라온다는 장점이 있다. 어느 쪽이든 프로젝트 전체에서 일관되게 유지하는 것이 중요하다.

<!-- 방법 1: 문서 하단에 모두 집중 -->
본문 내용...

[docs]: https://example.com
[install]: https://example.com/install

<!-- 방법 2: 참조 섹션 바로 아래 -->
[설치 가이드][install]를 참고합니다.

[install]: https://example.com/install

식별자가 너무 많아지면 정의 목록 자체가 관리 부담이 된다

참조형 링크 정의가 20개 이상 쌓이면 소스 하단이 복잡해지고, 사용되지 않는 링크 정의가 남아 혼란을 줄 수 있다. 이 시점에서는 인라인 링크로 전환하거나, 참조 문서를 별도 페이지로 분리하는 것이 더 나은 선택일 수 있다. 참조형 링크가 가장 빛나는 상황은 반복 링크가 5개 이상이고 URL이 길거나 변경 가능성이 있는 경우다.

선택 기준

주의할 점