Quick Comparison

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

완전한 URL은 Markdown renderer 전반에서 가장 이식성이 높고, #123, owner/repo#456, SHA는 GitHub의 문맥 의존 참조입니다. README나 외부 문서에서 반드시 이동시켜야 할 대상은 명시적 [링크](URL)로 쓰고, GitHub issue·PR 대화에서는 짧은 참조로 현재 저장소 맥락을 활용합니다.

문법

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

GitHub는 URL과 짧은 GitHub 참조를 같은 범위에서 처리하지 않는다. #123처럼 이슈나 PR을 가리키는 짧은 참조는 GitHub conversation에서 링크로 바뀌며, wiki나 repository file에서는 생성되지 않는다. 반면 완전한 URL(https://...)은 GFM의 URL autolink 확장을 지원하는 GitHub Markdown 표면에서 링크가 될 수 있다. 외부 문서까지 같은 결과가 필요하면 명시적 링크를 쓴다.

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

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

교차 저장소 참조에는 저장소 이름까지 적는다

같은 저장소의 이슈나 PR은 #123으로 참조하고, 다른 저장소의 이슈는 owner/repo#456처럼 저장소 이름까지 적는다. 커밋은 full SHA나 GitHub가 인식하는 SHA 참조를 쓸 수 있지만, 짧은 SHA는 저장소의 이력과 도구에 따라 모호해질 수 있다. 외부 공유 자료에서는 커밋 URL이나 full SHA를 함께 남기면 대상이 분명해진다.

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

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

<!-- 커밋 SHA 또는 커밋 URL -->
a5c3785ed8d6a35868bc169f07e40e889087fd2e

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

자동 링크에만 의존하면 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을 앵글 브라켓으로 감싸면 URI autolink으로 해석된다. GitHub에서는 앵글 브라켓 없이도 URL autolink 확장을 지원하지만, 다른 환경과 호환해야 한다면 앵글 브라켓이나 명시적 링크를 쓴다.

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

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

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

선택 기준

주의할 점

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

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