빠른 설정
[](https://example.com/build)이미지 기준
이미지 문법은 링크 문법 앞에 !를 붙인다
Markdown 이미지는 링크와 비슷하지만 앞에 !가 붙습니다. 대괄호 안은 alt text이고, 괄호 안은 image destination입니다.
alt text는 이미지가 보이지 않을 때의 대체 텍스트이자, 스크린 리더가 이미지를 이해하는 단서입니다. 파일명 설명이나 장식 문구보다 이미지가 전달하는 정보를 짧게 적는 편이 좋습니다.
저장소 안 이미지는 상대 경로가 유지보수에 유리하다
GitHub 문서에서는 repository 안 이미지를 보여 줄 때 absolute URL보다 relative link 사용을 권장합니다. 상대 경로를 쓰면 fork, branch, repository 이동 상황에서도 문서와 이미지가 함께 움직입니다.
문서 위치가 바뀌면 상대 경로도 함께 바뀌므로, 이미지 폴더를 문서와 가까운 위치에 두거나 docs 전체에서 일관된 asset 규칙을 정해야 합니다.
이미지 크기와 caption은 Markdown 표준만으로 부족하다
기본 Markdown 이미지 문법에는 width, height, caption을 지정하는 표준 문법이 없습니다. GitHub나 정적 사이트에서 크기 조정, figure caption, lazy loading이 필요하면 HTML, MDX component, renderer 전용 확장을 써야 합니다.
<img src="./assets/chart.png" alt="월별 가입자 추이" width="480" />다만 HTML이나 MDX를 쓰면 portability가 낮아질 수 있으므로, 문서가 여러 renderer로 이동하는지 먼저 확인해야 합니다.
선택 기준
| 상황 | 권장 방식 |
|---|---|
| README의 저장소 이미지 | 상대 경로 |
| 외부 CDN 이미지 | absolute URL |
| 접근성이 필요한 설명 이미지 | 의미 중심 alt text |
| 장식용 이미지 | 빈 alt 또는 renderer 정책 확인 |
| 이미지 크기 제어 필요 | HTML/MDX 확장 검토 |
| 문서 이식성 중요 | 표준 이미지 문법 유지 |
주의할 점
alt text를 파일명처럼 쓰면 이미지가 전달하는 정보를 잃습니다. 반대로 이미지 크기나 caption을 위해 HTML을 섞으면 renderer 호환성이 낮아질 수 있습니다. 접근성과 이식성 중 무엇이 더 중요한 문서인지 먼저 정해야 합니다.
상대 경로는 현재 Markdown 파일 위치를 기준으로 해석됩니다. 같은 이미지가 로컬 preview에서는 보이는데 GitHub나 정적 사이트에서 깨진다면, 빌드 후 public path와 repository 기준 경로가 같은지 확인해야 합니다.
참고 링크
2 sources