숏컷 코드

Visit https://github.com
#123
owner/repo#456
a5c3785ed3

문법

맥락에 따라 자동 링크 동작 범위가 달라진다

GitHub는 이슈·PR 코멘트, 커밋 메시지, 위키, 릴리스 노트, README 등 여러 문맥에서 텍스트를 분석해 링크를 만든다. 그런데 동작 범위는 맥락에 따라 다르다. #123처럼 단순한 이슈 번호 참조는 저장소 대화 맥락(이슈, PR 코멘트)에서는 항상 자동 링크가 되지만, 일반 README 파일 안에서는 렌더링 시 링크가 생성되지 않을 수 있다. 반면 완전한 URL(https://...)은 거의 모든 GitHub 맥락에서 자동 링크가 된다.

<!-- 이슈 코멘트: 아래 모두 자동 링크됨 -->
배포 오류는 #128에서 추적 중입니다.
원인 분석은 org/app#532와 커밋 a5c3785를 같이 확인하세요.

<!-- README 파일: URL만 자동 링크, #번호는 링크가 안 될 수 있음 -->
문서는 https://docs.github.com 에서 볼 수 있습니다.

교차 저장소 참조는 owner/repo#번호 형식이어야 한다

같은 저장소의 이슈나 PR은 #123으로 참조하지만, 다른 저장소의 이슈는 owner/repo#456 처럼 전체 형식으로 써야 자동 링크가 생성된다. 커밋 SHA는 7자 이상의 hex 문자열을 인식하며, 짧게 쓸수록 충돌 가능성이 있어 최소 7자 이상을 권장한다. 이 규칙을 모르면 의도한 링크가 생성되지 않아 독자가 참조를 수동으로 찾아야 하는 불편함이 생긴다.

<!-- 같은 저장소 이슈 -->
#532

<!-- 다른 저장소 이슈 -->
myorg/backend#532

<!-- 커밋 SHA (7자 이상 권장) -->
a5c3785ed3

자동 링크는 편리하지만 문서 이식성을 떨어뜨린다

자동 링크에만 의존하면 GitHub 바깥 환경(로컬 Markdown 뷰어, pandoc 변환, 다른 Git 호스팅)에서는 참조가 일반 텍스트로만 보인다. 정식 문서나 외부 공유 자료에서는 명시적 링크 [이슈 #128](https://github.com/owner/repo/issues/128) 형식이 더 안전하다. 자동 링크는 팀 내부 협업 문서처럼 GitHub를 공통 환경으로 쓸 때 가장 효과적이다.

<!-- 이식성 낮음: GitHub 밖에서는 링크가 보이지 않음 -->
#128을 참고하세요.

<!-- 이식성 높음: 어디서나 클릭 가능 -->
[이슈 #128](https://github.com/owner/repo/issues/128)을 참고하세요.

URL 자동 링크는 앵글 브라켓으로 강제할 수 있다

CommonMark 기준 <https://example.com> 처럼 URL을 앵글 브라켓으로 감싸면 모든 CommonMark 호환 렌더러에서 링크가 강제 생성된다. GitHub에서는 앵글 브라켓 없이도 대부분 자동 링크가 되지만, 다른 환경과 호환해야 한다면 명시적 형식이 더 안정적이다.

실무에서는 "GitHub 코멘트 안에서만 잘 되던 참조"를 README나 외부 문서에 그대로 옮기는 실수가 잦다. #123과 SHA 자동 링크는 맥락 의존적이라, 공개 문서로 나갈수록 명시적 링크가 더 안전하다.

<!-- CommonMark 표준 자동 링크 (앵글 브라켓) -->
<https://example.com>

<!-- GitHub 확장: 앵글 브라켓 없이도 링크됨 -->
https://example.com

선택 기준

주의할 점

배포 오류는 #128을 참고하세요.

이 문장은 GitHub 이슈 코멘트에서는 편하지만, 일반 Markdown 렌더러나 다른 호스팅으로 옮기면 그냥 텍스트가 될 수 있습니다.