기본 이미지 문법은 크기를 못 정합니다
마크다운의 기본 이미지 문법은 크기 옵션이 없습니다. 원본 그대로 들어갑니다.
마크다운이 "문서의 내용"만 다루고 "보이는 모양"은 렌더러에 맡기는 방향으로 설계됐기 때문입니다. 크기·색·글꼴 같은 표현은 애초에 문법에 넣지 않았습니다. 그래서 크기를 조절하려면 HTML <img> 태그를 써야 합니다.
<img>의 width / height
너비(width)나 높이(height)를 픽셀이나 퍼센트로 지정합니다.
<img src="image.png" alt="설명" width="300">
<img src="image.png" alt="설명" width="50%">
보통 width만 지정하면 비율이 유지된 채 크기가 조절됩니다. 가로·세로를 모두 적으면 그 크기에 정확히 맞춰지므로, 비율이 다르면 이미지가 찌그러집니다.
<img src="image.png" alt="설명" width="300" height="200">
특별한 이유가 없다면 width 하나만 쓰는 것을 권합니다.
⚠️ alt를 빠뜨리지 마세요
에서 대괄호 안이 대체 텍스트(alt)입니다. HTML 태그로 바꾸는 순간 이걸 빠뜨리기 쉽습니다.
alt는 이미지가 로드되지 않았을 때 대신 보이고, 화면 낭독기를 쓰는 사람에게는 그 자리에서 유일한 정보입니다. GitHub의 이미지가 가끔 로드에 실패하는 걸 생각하면 실용적인 이유도 충분합니다. <img>로 바꿔 쓸 때는 alt를 함께 옮기세요.
픽셀과 퍼센트, 뭘 써야 할까
| 지정 방식 | 동작 | 적합한 경우 |
|---|---|---|
width="300" |
항상 300px 고정 | 로고, 배지, 아이콘 |
width="50%" |
화면 폭의 절반 | 본문 폭에 맞춰야 하는 스크린샷 |
여기서 자주 놓치는 게 모바일입니다. width="800"처럼 큰 고정값을 주면 좁은 화면에서 이미지가 잘리거나 가로 스크롤이 생깁니다. GitHub처럼 컨테이너 폭을 넘지 않게 알아서 줄여주는 곳도 있지만, 모든 환경이 그렇지는 않습니다.
스크린샷처럼 큰 이미지는 퍼센트로, 로고나 배지처럼 작고 크기가 정해진 이미지는 픽셀로 지정하는 게 무난합니다.
고해상도 화면에서 흐릿하게 보인다면
맥북이나 최신 스마트폰처럼 고해상도 화면에서는 이미지가 뿌옇게 보이는 일이 있습니다. 화면의 실제 픽셀이 논리적 픽셀보다 두 배 이상 촘촘해서, 300px짜리 이미지를 300px 자리에 넣으면 늘려 그리는 셈이 되기 때문입니다.
해결은 간단합니다. 이미지를 표시할 크기의 두 배로 준비하고, width는 원하는 크기로 지정하면 됩니다.
<!-- 600px 이미지를 300px 자리에 표시 -->
<img src="logo@2x.png" alt="로고" width="300">
이러면 일반 화면에서는 깔끔하게 축소되어 보이고, 고해상도 화면에서는 원본 픽셀을 활용해 선명하게 나옵니다. 스크린샷을 찍어 README에 넣을 때 특히 체감 차이가 큽니다.
⚠️ 크기를 줄여도 용량은 그대로입니다
중요한 오해가 하나 있습니다. width="300"은 보이는 크기만 줄입니다. 파일 용량은 그대로입니다.
4000px짜리 스크린샷을 width="300"으로 넣으면 화면에는 작게 보이지만, 독자의 브라우저는 여전히 원본 전체를 내려받습니다. 이미지가 여러 장이면 문서가 눈에 띄게 느려지고, 모바일 데이터를 쓰는 사람에게는 그대로 비용입니다.
표시할 크기에 맞춰 이미지 자체를 줄여서 넣으세요. 화면 폭 기준으로 대략 이 정도면 충분합니다.
- 본문 전체 폭 스크린샷 — 1200~1600px
- 본문 절반 크기 — 800px
- 로고·아이콘 — 표시 크기의 2배
이지 마크다운 에디터는 이미지를 붙여넣을 때 가로 최대 1280px로 자동 압축합니다. 브라우저 저장 공간에 문서를 보관하는 구조라 원본을 그대로 두면 금방 한계에 부딪히기 때문인데, 결과적으로 위 기준과 비슷하게 맞춰집니다.
GitHub에서도 됩니다
GitHub은 <img>의 width, height 속성을 허용하므로 위 방법이 README·이슈에서 그대로 작동합니다.
단, style 속성은 제거됩니다. 보안상 인라인 스타일을 걷어내기 때문인데, 그래서 크기는 반드시 style="width:300px"이 아니라 width="300" 속성으로 지정해야 합니다. 글자 색이 GitHub에서 안 먹는 것과 같은 이유입니다.
GitHub 전용: 다크 모드에 따라 다른 이미지
GitHub에는 테마에 따라 이미지를 바꿔주는 기능이 있습니다. 흰 배경용 로고가 다크 모드에서 안 보이는 문제를 해결할 때 씁니다.
주소 끝에 표시를 붙이면 해당 테마에서만 보입니다. <picture> 태그를 쓰는 방법도 있습니다. 다만 GitHub 전용이라 다른 곳에서는 동작하지 않고, 주소에 붙은 표시가 그대로 남아 이미지가 깨질 수 있습니다.
정렬과 함께 쓰기
이미지를 가운데 두면서 크기도 줄이려면 정렬용 태그로 감쌉니다.
<p align="center">
<img src="logo.png" alt="로고" width="200">
</p>
배지 여러 개를 한 줄에 가운데 정렬하는 것도 같은 방식입니다. 가운데 정렬에 대한 자세한 내용은 따로 정리해두었습니다.
플랫폼별 지원
| 플랫폼 | <img width> |
비고 |
|---|---|---|
| GitHub | 동작 | style은 제거됨 |
| 벨로그 | 동작 | |
| 티스토리 | 동작 | 에디터에서 직접 조절하는 게 편함 |
| 노션 | 안 됨 | 이미지 모서리를 끌어 조절 |
| Slack·Discord | 안 됨 | 크기 조절 불가 |
노션이나 메신저처럼 HTML을 받지 않는 곳에서는 태그가 글자 그대로 노출됩니다. 이런 플랫폼은 이미지를 올린 뒤 마우스로 크기를 조절하는 방식이므로, 마크다운으로 크기를 지정하려 애쓸 필요가 없습니다.
정리하면, 이미지 크기는 가 아니라 <img width="...">로 조절하고, GitHub에서도 style이 아닌 width/height 속성이면 정상 적용됩니다. 그리고 보이는 크기를 줄이는 것과 파일을 줄이는 것은 다른 일이라는 점을 기억하세요.