가이드

2026 Markdown 이미지 문법 치트시트: GitHub, Notion, HackMD 4개 플랫폼 완전 정리

게시일2026. 3. 15.13 min read

Markdown 이미지 기본 문법은 ![대체 텍스트](이미지 URL)이며 모든 플랫폼에서 지원
이미지 크기 조절 방법은 플랫폼마다 전부 다르다 — 이것이 가장 큰 함정
이미지는 반드시 "공개 접근 가능한 직접 링크"여야 하며, Google Drive 공유 링크는 불가

자, 이제 전체 치트시트를 살펴보겠습니다.

기본 문법: 모든 플랫폼 공통

![대체 텍스트](https://example.com/image.png)

대체 텍스트: 이미지를 표시할 수 없을 때 나타나는 텍스트이자, 스크린 리더가 읽는 내용
이미지 URL: 직접 접근 가능한 이미지 URL(직접 링크)이어야 함

제목 추가(마우스 호버 시 표시):

![대체 텍스트](https://example.com/image.png "마우스를 올리면 나타나는 제목")

참조 형식 문법(같은 이미지를 반복 사용할 때 적합):

![대체 텍스트][logo]

[logo]: https://example.com/image.png "제목"

플랫폼별 이미지 크기 조절 방법

이 부분이 가장 실수하기 쉬운 곳입니다. 5개 주요 플랫폼을 실제로 테스트한 결과, 각각의 방법이 모두 다릅니다.

플랫폼	크기 조절 문법	예시
GitHub	Markdown 조절 미지원, HTML 필요	`<img src="url" width="300">`
HackMD	URL 뒤에 `=너비x높이` 추가	`![alt](url =300x200)`
Notion	드래그로 조절, 문법 제어 없음	업로드 후 마우스로 테두리 드래그
Obsidian	alt에 `	너비`또는`
Typora	HTML 또는 zoom 표기 사용	`<img src="url" style="zoom:50%">`

GitHub

GitHub의 Markdown 렌더러는 어떠한 이미지 크기 문법도 지원하지 않습니다. 유일한 방법은 HTML을 사용하는 것입니다:

<img src="https://example.com/image.png" width="400" alt="설명 텍스트">

GitHub는 <img> 태그의 width, height, align 속성을 지원하지만, style 속성은 보안상의 이유로 필터링됩니다.

HackMD

HackMD는 커스텀 확장 문법을 사용하여 URL 뒤에 =너비x높이를 추가합니다:

![설명 텍스트](https://example.com/image.png =300x200)

너비만 지정하고 높이는 자동 조절:

![설명 텍스트](https://example.com/image.png =300x)

이 문법은 HackMD 전용이며 다른 플랫폼에서는 작동하지 않습니다.

Obsidian

Obsidian의 이미지 크기 문법은 대체 텍스트 안에 넣습니다:

![설명 텍스트|300](https://example.com/image.png)
![설명 텍스트|300x200](https://example.com/image.png)

Obsidian은 Wiki 스타일의 내부 이미지 링크도 지원합니다:

![[image.png|300]]

Notion

Notion의 Markdown 가져오기는 기본 이미지 문법을 지원하지만, 크기 조절은 Notion 인터페이스에서 마우스 드래그로만 가능합니다. 문법 제어 옵션은 없습니다.

또한 주의할 점: Notion은 외부 이미지를 자체 CDN(prod-files-secure.s3.us-west-2.amazonaws.com)에 재업로드하므로, 이미지 출처가 표시 속도에 영향을 주지 않습니다. 다만 원본 이미지를 업데이트해도 Notion의 버전은 갱신되지 않습니다.

플랫폼별 이미지 호스팅 지원 현황

모든 이미지 URL이 모든 플랫폼에서 정상 표시되는 것은 아닙니다. 실측 결과는 다음과 같습니다:

이미지 출처	GitHub	HackMD	Notion	Obsidian	Typora
이미지 호스팅 직접 링크(lpic.cc, ImgBB 등)	정상	정상	정상	정상	정상
GitHub 저장소 내 이미지	정상	정상	정상	설정 필요	정상
Google Drive 공유 링크	표시 안 됨	표시 안 됨	자동 재업로드	불안정	표시 안 됨
Dropbox 공유 링크	표시 안 됨	표시 안 됨	자동 재업로드	불안정	표시 안 됨
Base64 인라인	지원	지원	미지원	지원	지원

핵심: Google Drive와 Dropbox의 공유 링크는 이미지 직접 링크가 아니므로, 대부분의 Markdown 플랫폼에서 올바르게 렌더링할 수 없습니다. Markdown에 이미지를 삽입하려면 "직접 링크"를 제공하는 이미지 호스팅 서비스가 필요합니다.

핫링킹 정책: 이미지가 차단될 수 있을까?

핫링킹(Hotlinking)은 자신의 웹페이지에서 다른 서버에 있는 이미지를 직접 참조하는 것입니다. 일부 서비스는 대역폭 절감을 위해 핫링킹을 차단합니다.

서비스	핫링킹 허용	비고
이미지 호스팅 서비스(lpic.cc, ImgBB 등)	예	이미지 호스팅의 핵심 기능
GitHub 저장소	예(제한 있음)	높은 트래픽 시 제한될 수 있음
Imgur	일부(대만 차단됨)	2025년 이후 대만 IP 접근 불가
WordPress.com	아니요	Referer 검사
대부분의 웹사이트 이미지	아니요	보통 외부 참조 차단

기술 글쓰기에서의 이미지 모범 사례

기술 문서나 블로그를 작성할 때 이미지 처리의 몇 가지 원칙:

대체 텍스트를 대충 쓰지 않기

<!-- 부적절 -->
![image](url)
![스크린샷](url)

<!-- 적절 -->
![GitHub Actions 워크플로 설정 페이지](url)
![터미널에서 npm install 성공 출력 결과](url)

대체 텍스트의 기능:

이미지 로딩 실패 시 텍스트 설명 표시
스크린 리더가 읽어주는 내용(접근성 설계)
검색 엔진이 이미지 내용을 파악하는 데 활용(SEO)

이미지 파일 명명

<!-- 부적절 -->
Screenshot 2026-03-15 at 14.32.05.png
IMG_4521.jpg

<!-- 적절 -->
github-actions-workflow-config.png
npm-install-success-output.png

좋은 파일명은 6개월 후에도 이 이미지가 무엇인지 한눈에 알 수 있게 해줍니다.

이미지 포맷 선택

스크린샷, UI 인터페이스: PNG(선명한 텍스트가 흐려지지 않음)
사진, 복잡한 이미지: WebP 또는 JPEG(파일 크기가 작음)
아이콘, 로고, 차트: SVG(확대/축소해도 선명)
동적 작업 과정 시연: GIF 또는 WebP 애니메이션(단, 5MB 이하로 제한)

압축 후 업로드

어떤 포맷이든 업로드 전에 먼저 압축하세요. 추천 도구:

Squoosh(squoosh.app) — Google 제작, 브라우저에서 바로 사용
TinyPNG(tinypng.com) — PNG/JPEG 일괄 압축
ImageOptim(macOS) — 드래그 앤 드롭으로 바로 압축, 화질 유지

크로스 플랫폼 호환 만능 작성법

Markdown 문서가 여러 플랫폼에서 정상 표시되어야 한다면 다음 전략을 사용하세요:

이미지 문법: 표준 ![alt](url) 문법을 사용하고, 플랫폼 전용 크기 조절 문법은 사용하지 않기
이미지 크기: 업로드 전에 이미지 크기를 미리 조정(너비 600-800px 권장), 문법으로 제어하지 않기
이미지 출처: 이미지 호스팅 직접 링크 사용(예: lpic.cc는 가입 없이 업로드 및 직접 링크 제공), Google Drive나 Dropbox 공유 링크 사용하지 않기
이미지 포맷: PNG 또는 WebP, BMP나 TIFF는 피하기

다만 lpic.cc는 현재 이미지 크기 맞춤 설정이나 실시간 자르기를 지원하지 않으므로, 업로드 전에 이미지를 미리 처리해야 합니다. API 일괄 업로드나 동적 처리가 필요하다면 Cloudinary나 Imgur API(한국 외 지역) 등의 서비스를 고려해야 합니다.

자주 묻는 질문 FAQ

Q1: Markdown에서 이미지를 가운데 정렬할 수 있나요?

표준 Markdown 문법은 이미지 정렬을 지원하지 않습니다. GitHub에서는 HTML을 사용할 수 있습니다: <p align="center"><img src="url" width="400"></p>. HackMD는 {:center} 문법을 지원합니다. Notion과 Obsidian은 UI에서 조절합니다.

Q2: Markdown에서 로컬 이미지를 사용할 수 있나요?

가능합니다. 상대 경로를 사용하면 됩니다: ![alt](./images/photo.png). 다만 이는 로컬 편집기(Typora, Obsidian, VS Code)에서만 유효합니다. 문서를 웹에 게시하려면 이미지를 이미지 호스팅에 업로드하여 공개 URL을 확보해야 합니다.

Q3: GitHub README에서 이미지가 표시되지 않는 이유는?

가장 흔한 원인 세 가지: (1) 이미지 URL이 직접 링크가 아니라 로그인이 필요한 링크; (2) 이미지 출처 서버가 GitHub의 핫링킹을 차단; (3) 상대 경로가 잘못되어 저장소 내 올바른 위치와 매칭되지 않음.

Q4: HackMD의 이미지 크기 문법 `=300x`가 다른 플랫폼에서도 작동하나요?

작동하지 않습니다. =너비x높이 문법은 HackMD 전용 Markdown 확장이며, GitHub, Notion, Obsidian 등의 플랫폼에서는 적용되지 않습니다. 크로스 플랫폼 문서라면 업로드 전에 이미지 크기를 미리 조정하거나, HTML <img> 태그를 사용하는 것이 좋습니다(GitHub와 HackMD 모두 지원).

Q5: 이미지 직접 링크와 공유 링크의 차이는?

직접 링크(Direct Link)는 이미지 파일을 직접 가리키는 URL로, 보통 .jpg, .png, .webp로 끝납니다. 브라우저로 열면 이미지만 보입니다. 공유 링크는 웹페이지 URL로, 열면 이미지가 포함된 페이지(예: Google Drive 미리보기 페이지)가 표시됩니다. Markdown의 이미지 문법은 직접 링크여야 올바르게 렌더링됩니다.

참고 자료

Markdown Guide - Images — Markdown 공식 이미지 문법 문서
GitHub - Basic formatting syntax — GitHub Markdown 문법 문서
HackMD - Supported Markdown Syntax — HackMD 지원 Markdown 문법
Obsidian - Embed files — Obsidian 파일 임베드 문서
MDN - HTML img element — HTML img 태그 참고

#Markdown#GitHub#Notion#HackMD#이미지 문법#기술 글쓰기

작성자

Mia Huang

효율화 전문가

한 번에 끝낼 수 있는 일은 절대 두 번 하지 않습니다. 시간과 노력을 아끼는 간편 가이드를 전문으로 작성합니다.

긴 글 읽기 귀찮다면? 세 줄 요약