Markdown 하나로 기술 블로그에 이미지와 영상을 넣는 방법

기술 글을 쓰다 보면 코드만으로 설명하기 어려운 순간이 있다. 화면의 흐름은 이미지가 가장 빠르고, 실제 동작은 영상이 가장 정확하다. 그래서 이번 블로그에는 Markdown 안에서 이미지, 캡션, SVG, 영상 임베드를 함께 사용할 수 있는 작성 방식을 정리했다.

글 폴더에 미디어를 함께 둔다

하나의 글을 다음처럼 폴더로 관리한다.

1blog/
2└── 2026-10-01-markdown-media/
3    ├── index.md
4    ├── media-flow.svg
5    └── video-layout.svg

이미지를 글 폴더에 두면 빌드 과정에서 공개 경로로 자동 복사된다. 글과 이미지가 멀리 떨어지지 않기 때문에 나중에 글을 옮기거나 수정할 때도 어떤 파일이 어떤 설명에 쓰였는지 바로 알 수 있다.

가장 간단한 이미지는 Markdown 문법으로 쓴다

1![대체 텍스트](screen.png)

이미지의 경로는 현재 글 폴더를 기준으로 해석된다. 본문에 표시되는 이미지는 클릭하면 크게 볼 수 있고, alt 텍스트는 이미지 설명과 접근성에 함께 사용된다.

좋은 대체 텍스트는 이미지의 파일명이 아니라 이미지에서 확인할 수 있는 정보를 적는다.

1![배포 전후의 빌드 상태를 비교한 터미널 화면](deploy-result.png)

반대로 screen1.png처럼 파일명만 적으면 이미지가 보이지 않는 상황에서 글의 의미를 전달하기 어렵다. 캡처 화면이라면 무엇을 보여주는지, 다이어그램이라면 어떤 관계를 설명하는지 짧게 적는 편이 좋다.

캡션이 필요한 이미지는 HTML을 섞는다

이미지 아래에 출처나 설명을 명확히 남겨야 한다면 figure와 figcaption을 사용한다.

1<figure>
2  <img src="architecture.svg" alt="요청이 웹 서버와 데이터베이스를 거치는 흐름">
3  <figcaption>요청 흐름을 단순화해 그린 구조도.</figcaption>
4</figure>

HTML을 사용해도 이미지 경로와 반응형 폭은 일반 Markdown 이미지와 같은 규칙으로 동작한다. 다만 이미지 안에 이미 글자가 포함돼 있더라도 alt에는 이미지 전체의 의미를 다시 적어 두는 것이 좋다.

영상은 16:9 비율로 임베드한다

YouTube 영상은 원본 링크를 그대로 붙이는 대신 youtube-nocookie.com 임베드 주소를 사용한다.

1<figure class="video">
2  <iframe
3    src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
4    title="영상에서 확인할 수 있는 내용"
5    loading="lazy"
6    allow="accelerometer; autoplay; encrypted-media; picture-in-picture"
7    allowfullscreen
8  ></iframe>
9  <figcaption>영상의 핵심 장면과 출처를 한 줄로 설명한다.</figcaption>
10</figure>

영상은 모바일에서 화면 밖으로 튀어나오지 않도록 본문 폭에 맞춰 줄어든다. title은 플레이어를 읽어 주는 사용자에게 필요하고, loading="lazy"는 글을 읽기 시작할 때 영상을 바로 불러오지 않도록 해 초기 로딩 부담을 줄인다.

직접 녹화한 짧은 데모 영상은 글 폴더에 넣고 다음처럼 쓸 수 있다.

1<video src="demo.mp4" controls preload="metadata"></video>

현재 빌드에서는 mp4, webm, ogg, mov, m4v 파일을 이미지와 같은 방식으로 공개 경로에 복사한다. 긴 영상은 저장소 크기를 빠르게 키울 수 있으므로 YouTube나 Vimeo에 올리고 임베드하는 편이 운영하기 쉽다.

글이 풍성해지는 순서

미디어를 많이 넣는 것보다 글의 흐름에 맞춰 배치하는 것이 중요하다.

1. 문제와 결론을 먼저 글로 설명한다.
2. 글만 읽어도 이해할 수 있도록 핵심 조건과 숫자를 적는다.
3. 구조나 화면처럼 한눈에 보여주는 편이 빠른 내용에 이미지를 넣는다.
4. 직접 조작하는 과정이나 시간 흐름이 중요한 내용에 영상을 넣는다.
5. 모든 미디어에 대체 텍스트, 캡션, 출처를 붙인다.

이미지는 설명을 대신하는 장식이 아니라 독자가 다음 문단을 이해하도록 돕는 이정표다. 영상도 재생하지 않아도 무엇을 보여주는지 알 수 있어야 한다. 이 원칙만 지키면 Markdown 글도 문서와 데모 사이의 균형을 잡을 수 있다.

이번 블로그에서의 작성 규칙

• 글과 관련된 이미지는 글 폴더에 둔다.
• 파일명은 screen1.png보다 deploy-success.png처럼 의미를 담는다.
• 모든 이미지에 구체적인 alt를 작성한다.
• 출처가 있는 이미지와 영상에는 캡션이나 참고 링크를 남긴다.
• 영상은 짧게 유지하고, 긴 내용은 외부 플랫폼에 임베드한다.
• 개인정보, 토큰, 내부 주소가 보이는 화면은 공개 전에 가린다.

이제 기술 글에 코드만 나열하지 않고, 흐름을 그린 SVG와 실제 동작을 보여주는 영상까지 같은 글 안에서 관리할 수 있다. 중요한 건 미디어를 먼저 채우는 것이 아니라, 독자가 가장 빨리 이해할 수 있는 위치에 정확한 설명과 함께 놓는 것이다.