빠른 비교
| 목적 | Markdown만으로 가능 | 대안 |
|---|---|---|
| 이미지 삽입 | 가능 |  |
| alt text | 가능 | 대체 텍스트 작성 |
| width/height 지정 | 표준 Markdown에는 없음 | HTML 또는 컴포넌트 |
| caption | 표준 Markdown에는 없음 | figure/figcaption |
| 반응형 이미지 | 렌더러 의존 | 사이트 이미지 컴포넌트 |
<figure>
<img src="./images/dashboard.png" alt="대시보드 화면" width="720" />
<figcaption>관리자 대시보드의 주요 지표 영역</figcaption>
</figure>경계
Markdown 이미지 문법은 alt와 destination이 중심이다
기본 이미지 문법은 링크 문법 앞에 !를 붙인 형태입니다. 이 문법의 핵심은 이미지 파일을 연결하고, 이미지가 보이지 않거나 스크린 리더가 읽을 수 있는 alt text를 제공하는 것입니다.
크기, 정렬, caption은 CommonMark 이미지 문법의 핵심 기능이 아닙니다. GitHub README처럼 렌더러가 정해진 문서에서는 기본 이미지 문법만으로 충분한 경우가 많지만, 제품 문서나 튜토리얼에서는 caption과 크기 제어가 필요해질 수 있습니다.
크기 조절은 HTML이나 렌더러 확장에 의존한다
Markdown에는 표준 width/height 문법이 없습니다. 일부 도구는  같은 확장을 지원하지만 이식성이 낮습니다. 여러 렌더러로 이동할 문서라면 raw HTML이나 사이트 전용 이미지 컴포넌트를 쓰는 것이 의도를 더 명확히 드러냅니다.
<img src="./diagram.png" alt="배포 흐름" width="640" />MDX 문서에서는 이미지 최적화 컴포넌트를 쓸 수 있지만, 그 순간 문서는 일반 Markdown이 아니라 빌드 파이프라인에 묶입니다.
caption은 이미지 설명과 alt text를 대체하지 않는다
caption은 화면에 보이는 설명이고, alt text는 이미지 대체 텍스트입니다. 둘은 목적이 다릅니다. caption을 넣었다고 alt를 비워 두면 접근성과 검색 맥락이 약해질 수 있습니다.
<figure>
<img src="./flow.png" alt="로그인 요청에서 세션 발급까지의 흐름" />
<figcaption>로그인 API 처리 흐름</figcaption>
</figure>장식용 이미지라면 alt를 비울 수 있지만, 기술 문서의 다이어그램과 스크린샷은 대개 의미를 갖습니다. 이 경우 caption보다 alt text를 먼저 정확히 써야 합니다.
선택 기준
| 상황 | 선택 |
|---|---|
| README의 단순 스크린샷 | 기본 Markdown 이미지 |
| 크기 고정이 필요함 | HTML 또는 컴포넌트 |
| 그림 설명을 화면에 보여야 함 | figure + figcaption |
| 여러 렌더러로 이동 가능 | Markdown 기본 문법 우선 |
| 이미지 최적화가 중요함 | 사이트 전용 이미지 컴포넌트 |
주의할 점
이미지 크기와 caption을 렌더러별 확장 문법에 의존하면 문서 이동 시 깨질 가능성이 큽니다. GitHub, 정적 사이트, MDX, PDF 변환 중 어디에서 읽힐 문서인지 먼저 정하고 표현 방식을 고르세요.
HTML로 이미지를 넣으면 Markdown 이미지보다 보안 필터와 sanitization 영향을 더 많이 받습니다. 사용자 입력 Markdown에서는 허용 태그와 속성을 제한해야 합니다.
참고 링크
2 sources