Markdown 정복기 (2) — 코드, 표, 이미지
Markdown 시리즈 2편. 자주 쓰지만 자주 깨지는 영역 — 코드 블록(언어 지정, 라인 강조), 표(정렬), 이미지(크기·캡션)를 정리한다.
Series
Markdown 시리즈- 1Markdown 정복기 (1) — 기본 문법 한 번에 정리
- 2Markdown 정복기 (2) — 코드, 표, 이미지
- 3Markdown 정복기 (3) — GFM과 MDX 확장 문법
들어가며
1편이 어디서든 통하는 표준이었다면, 이 글은 자주 쓰지만 환경마다 미묘하게 깨지는 영역이다. 미리 패턴을 익혀두면 글이 한참 다 쓰고 나서 깨지는 사고를 막을 수 있다.
1) 코드 블록
인라인 코드
백틱 하나로 감싼다. 1편에서 다뤘다.
함수 `useState`는 React Hook이다.백틱이 들어간 코드를 인라인으로 보여주려면 백틱을 두 개 또는 세 개로 감싼다.
``코드 안에 `백틱` 들어있는 경우``펜스 코드 블록 — 가장 많이 쓰는 형태
세 개 백틱으로 감싸고, 첫 줄에 언어 이름을 명시한다.
```python
def hello():
print("hi")
```→
def hello():
print("hi")언어 이름은 python, javascript(또는 js), typescript(ts), bash, sh, json, yaml, tsx, css, html, sql, dockerfile 등 거의 다 지원한다. 언어 명시 없이 그냥 ```만 쓰면 syntax highlight가 안 된다 — 항상 명시하는 습관.
파일명 표시 (이 블로그 컨벤션)
이 블로그는 title="파일명.ext" 메타로 파일명을 표시한다.
```python title="utils/hello.py"
def hello():
print("hi")
```→
def hello():
print("hi")라인 강조 (블로그 시스템에 따라)
일부 시스템(rehype-pretty-code 등)은 {2-4} 같은 메타로 특정 줄을 강조한다.
```ts {2-3}
function add(a: number, b: number) {
const result = a + b;
return result;
}
```블로그 빌드 설정에 달려있으니 본인 사이트에서 한 번 테스트해볼 것.
리스트 안에 코드 블록
리스트 항목 아래에 코드 블록을 두려면 4칸 들여쓰기 + 빈 줄이 안전하다.
1. 먼저 설치한다.
```bash
npm install foo
```
2. 그다음 import 한다.
```ts
import foo from "foo";
```들여쓰기를 2칸만 해도 동작하는 시스템이 많지만, 안전하게는 4칸.
코드 블록 안에 코드 블록 보여주기
이 글처럼 markdown 자체를 설명할 때 종종 필요하다. 바깥 펜스를 더 길게 쓰면 된다.
````md
```python
print("hi")
```
````5개 백틱으로 감싸면 4개 백틱이 들어있는 블록을 표현할 수 있다. 일종의 escape.
2) 표
기본 형태
| 헤더 1 | 헤더 2 | 헤더 3 |
|--------|--------|--------|
| 셀 1 | 셀 2 | 셀 3 |
| 셀 4 | 셀 5 | 셀 6 |→
| 헤더 1 | 헤더 2 | 헤더 3 |
|---|---|---|
| 셀 1 | 셀 2 | 셀 3 |
| 셀 4 | 셀 5 | 셀 6 |
정렬
구분선의 콜론 위치로 정렬을 지정한다.
| 왼쪽 | 가운데 | 오른쪽 |
|:-----|:------:|------:|
| L | C | R |→
| 왼쪽 | 가운데 | 오른쪽 |
|---|---|---|
| L | C | R |
:----왼쪽 정렬:----:가운데 정렬----:오른쪽 정렬
셀 안 줄바꿈
표 셀 안에서는 그냥 엔터를 치면 표가 깨진다. <br />로 강제한다.
| 항목 | 설명 |
|------|------|
| A | 첫 줄<br />둘째 줄 |셀 안 코드
인라인 코드는 표 안에서도 작동한다.
| 명령 | 설명 |
|------|------|
| `git add` | 스테이징 |
| `git commit -m "msg"` | 커밋 || 명령 | 설명 |
|---|---|
git add | 스테이징 |
git commit -m "msg" | 커밋 |
표가 너무 클 때
Markdown 표는 거대해지면 사람이 읽기 어렵다. 컬럼이 5개를 넘거나 셀에 긴 텍스트가 들어간다면, 이중 정렬 데이터셋보다는 항목별 헤딩 + bullet을 쓰는 편이 깔끔하다.
표 작성을 도와주는 도구 — VSCode의 "Markdown Table Formatter" 확장, 또는 tablesgenerator.com/markdown_tables. 손으로 정렬 맞추는 시간을 아낀다.
3) 이미지
기본 문법
! 하나가 차이지만 의미가 완전히 다르다 (링크 vs 이미지). 빠뜨리지 말 것.
경로 패턴
블로그 / Next.js 프로젝트의 경우:
public/images/attention.png에 두면 /images/attention.png로 참조한다. 외부 URL도 그냥 됨.
alt 텍스트는 진심이다
 — alt 텍스트 없는 이미지는 스크린 리더 사용자에게 통째로 사라진다. SEO에도 손해다. 한 줄이라도 적자.
크기 조절 — Markdown만으로는 안 된다
표준 Markdown에는 이미지 크기 옵션이 없다. 세 가지 우회법:
1) HTML 직접 사용
<img src="/images/diagram.png" alt="설명" width="400" />2) Next.js Image 컴포넌트 (MDX 기반 블로그)
이 블로그는 <Figure> 컴포넌트를 제공한다.
<Figure
src="/images/diagram.png"
alt="설명"
caption="아키텍처 다이어그램"
width={800}
height={450}
/>3) CSS 클래스 (블로그 시스템에 따라)
다음 편(GFM/MDX 확장)에서 자세히.
캡션
표준 Markdown에 캡션 문법은 없다. 그냥 이미지 다음 줄에 기울임으로 적는 관습이 흔하다.
*그림 1. 시스템 전체 아키텍처*또는 위에서 본 <Figure> 컴포넌트를 쓰면 caption이 의미적으로도 맞게 들어간다.
헷갈리는 케이스 모음
| 증상 | 원인 / 해결 |
|---|---|
| 코드 블록이 일반 문단처럼 나옴 | 백틱이 3개 미만이거나 양쪽 펜스가 다름 |
| 코드 안 한글이 깨짐 | 파일이 UTF-8이 아님 |
| 표가 그냥 텍스트로 나옴 | 헤더 아래 |---| 구분선 누락, 또는 양쪽 빈 줄 누락 |
| 이미지가 깨진 링크처럼 나옴 | 경로 오타 또는 public/ 누락. 루트는 /로 시작 |
| 들여쓰기가 안 먹힘 | 탭과 스페이스가 섞임 — 한 가지로 통일 |
정리 및 다음 편
지금까지가 Markdown으로 표현 가능한 거의 모든 시각 요소를 다뤘다. 코드, 표, 이미지 세 가지면 기술 글의 90%를 커버한다.
다음 편은 GFM(GitHub Flavored Markdown) 확장과 MDX의 React 컴포넌트 임베딩 — 표준을 넘어선 영역으로 들어간다. callout, footnote, 수식, 다이어그램까지.