마크다운(Markdown) 완전 가이드: 문법·GFM·실시간 미리보기

이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

GitHub에 README를 올리거나, Velog·노션에 글을 쓰거나,
기술 문서를 작성할 때 마크다운을 피할 수 없습니다. 마크다운을 모르면 **굵게**라고 입력해도 그대로 출력되고,
표를 만들려다 포기하는 상황이 생깁니다. 반대로 마크다운 문법을 익히면 복잡한 서식 도구 없이 깔끔한 문서를 빠르게 만들 수 있습니다.

이 가이드에서는 마크다운 기본 문법부터 GitHub Flavored Markdown(GFM) 확장 문법까지
실무에서 자주 쓰는 내용만 정리합니다.

마크다운 미리보기 도구 바로 사용하기 →

마크다운이란?#

마크다운(Markdown)은 2004년 존 그루버(John Gruber)가 만든 경량 마크업 언어 입니다. 일반 텍스트에 간단한 기호를 추가하면 HTML로 변환됩니다. # 제목이라고 쓰면 <h1>제목</h1>이 되는 방식입니다.

마크다운이 널리 쓰이는 이유는 세 가지입니다. 첫째, 특별한 소프트웨어 없이 메모장만 있어도 작성할 수 있습니다. 둘째, 일반 텍스트 파일이라 버전 관리가 쉽습니다. 셋째, GitHub·Notion·Discord·Velog 등 수백 개 플랫폼이
마크다운을 기본 지원합니다.

기본 문법 한눈에 보기#

아래는 마크다운에서 가장 자주 쓰는 기본 문법입니다.

목적	마크다운 입력	결과
제목 1단계	`# 제목`	큰 제목 (h1)
제목 2단계	`## 제목`	중간 제목 (h2)
제목 3단계	`### 제목`	작은 제목 (h3)
굵게	`텍스트`	굵게
기울임	`텍스트`	기울임
~~취소선~~	`~~텍스트~~`	~~취소선~~
순서 없는 목록	`- 항목` 또는 `* 항목`	• 항목
순서 있는 목록	`1. 항목`	1. 항목
링크	`[텍스트](URL)`	클릭 가능한 링크
이미지	`![설명](URL)`	이미지 삽입
인용	`> 인용문`	들여쓰기된 인용
인라인 코드	`코드`	`코드`
구분선	`---`	가로 구분선

줄바꿈 규칙 주의#

마크다운에서 단순히 Enter를 한 번 누르면 줄바꿈이 되지 않습니다. 새 단락으로 만들려면 빈 줄을 한 줄 추가해야 합니다. 같은 단락 내에서 강제 줄바꿈이 필요하다면
문장 끝에 공백 두 칸을 입력하거나 <br> 태그를 사용합니다.

GFM: GitHub가 확장한 마크다운#

GitHub Flavored Markdown(GFM)은 표준 마크다운에 편의 기능을 추가한 확장 규격입니다. GitHub뿐 아니라 Velog, GitLab, Obsidian 등
대부분의 현대 마크다운 도구가 GFM을 지원합니다.

표 만들기#

| 이름 | 나이 | 직업 |
|------|------|------|
| 홍길동 | 30 | 개발자 |
| 김철수 | 25 | 디자이너 |

첫 행이 헤더, 두 번째 행(하이픈 행)이 구분선입니다. 각 셀은 |로 구분합니다. 열 정렬은 |:---:|(가운데), |---:|(오른쪽)으로 지정합니다.

코드 블록#

코드 블록은 백틱 세 개(```)로 감쌉니다. 언어명을 지정하면 문법 강조가 적용됩니다.

```python
def hello():
    print("Hello, World!")
```

```javascript
const sum = (a, b) => a + b;
```

체크박스 (할 일 목록)

- [x] 완료된 항목
- [ ] 미완료 항목
- [ ] 다른 미완료 항목

GitHub Issues, Notion, Obsidian 등에서
체크박스를 클릭해 상태를 바꿀 수 있습니다.

플랫폼별 마크다운 지원 현황#

마크다운을 지원하는 주요 플랫폼과 지원 범위를 정리합니다.

플랫폼	기본 문법	GFM 표	코드 강조	수식(LaTeX)	비고
GitHub	✅	✅	✅	✅	GFM 원조
Velog	✅	✅	✅	✅	개발자 블로그
Notion	✅	✅	✅	✅	자체 확장 추가
Obsidian	✅	✅	✅	✅	로컬 마크다운
Discord	부분	❌	✅	❌	간소화 지원
티스토리	✅	✅	✅	❌	HTML 모드 전환 필요
Reddit	✅	✅	❌	❌	구버전 Reddit만
Slack	부분	❌	✅	❌	메시지용 간소화

마크다운 미리보기 도구 사용법#

작성한 마크다운이 실제로 어떻게 렌더링되는지 확인하려면 미리보기 도구를 활용합니다.

마크다운 미리보기 페이지에 접속합니다.
왼쪽 에디터 영역에 마크다운 텍스트를 입력하거나 붙여넣습니다.
오른쪽 미리보기 영역에서 렌더링 결과를 실시간으로 확인합니다.
표·코드블록·체크박스 등 GFM 문법도 즉시 확인됩니다.

VSCode를 사용하는 경우 Ctrl+Shift+V(Mac: Cmd+Shift+V)로
내장 마크다운 미리보기를 열 수 있습니다. 단, VSCode 미리보기는 GFM 일부 기능이 다르게 보일 수 있으므로,
GitHub·Velog 등 실제 게시 환경과 비교하려면 전용 도구를 활용하는 것이 정확합니다.

자주 하는 실수 TOP 5#

1. 제목 기호 뒤 띄어쓰기 누락
#제목은 제목으로 인식되지 않습니다. # 제목처럼 #과 텍스트 사이에 공백이 필요합니다.

2. 빈 줄 없이 목록 작성
목록 바로 위에 빈 줄이 없으면 일부 파서가 목록으로 인식하지 않습니다. 목록 시작 전 항상 빈 줄을 넣으세요.

3. 들여쓰기 단위 혼용
중첩 목록에서 탭과 스페이스를 혼용하면 렌더링이 깨질 수 있습니다. 스페이스 2칸 또는 4칸 중 하나로 통일합니다.

4. 특수문자 이스케이프 누락
마크다운 기호를 그대로 표시하려면 백슬래시로 이스케이프해야 합니다. 예: \*별표 그대로\*, \[대괄호\]. 이스케이프하지 않으면 마크다운 문법으로 해석됩니다.

5. 표 구분선 행 누락
| 헤더 | 다음 줄에 | --- | 구분선을 빠뜨리면 표로 렌더링되지 않습니다. 헤더 바로 아래 구분선 행은 필수입니다.

자주 묻는 질문#

Q. 마크다운과 HTML 중 어느 것을 써야 하나요?

A. 마크다운이 지원되는 환경에서는 마크다운이 훨씬 빠르고 가독성이 좋습니다. 다만 복잡한 레이아웃이나 세밀한 스타일이 필요하면 HTML이 필요합니다. 마크다운 안에 HTML 태그를 일부 섞어 쓸 수 있는 플랫폼도 있지만,
GitHub·Velog 등 보안 정책이 엄격한 플랫폼은 HTML을 제한합니다.

Q. GFM과 표준 마크다운의 차이는 무엇인가요?

A. 표준 마크다운은 존 그루버가 정의한 기본 규격입니다. GFM(GitHub Flavored Markdown)은 여기에 표·코드 강조·체크박스·취소선·URL 자동 링크 를
추가한 GitHub의 확장 규격입니다. 현재 대부분의 개발 환경에서는 GFM이 사실상 표준처럼 사용됩니다.

Q. 마크다운으로 이미지를 삽입할 수 있나요?

A. 네. ![대체 텍스트](이미지 URL) 문법으로 삽입합니다. 단, 이미지 URL이 외부 링크인 경우 해당 서버가 CORS를 허용해야 표시됩니다. 로컬 파일은 상대 경로로 참조할 수 있지만
웹에 게시할 때는 이미지 호스팅이 필요합니다.

Q. 마크다운에서 글자 색상이나 폰트를 바꿀 수 있나요?

A. 순수 마크다운으로는 불가능합니다. 색상·폰트 변경은 CSS나 HTML 태그(<span style="color:red">)가 필요한데,
플랫폼마다 HTML 허용 여부가 다릅니다. GitHub·Velog 등 보안 중심 플랫폼은 인라인 스타일을 제거합니다.

Q. 마크다운 파일을 PDF로 변환할 수 있나요?

A. 가능합니다. VSCode의 "Markdown PDF" 확장 프로그램, Pandoc 명령줄 도구, 또는 Typora 편집기를 사용하면
마크다운 파일을 PDF로 내보낼 수 있습니다. GitHub Actions를 활용한 자동화도 가능합니다.

마크다운은 배우는 데 30분이면 충분하지만,
익혀두면 개발 문서·블로그·기술 노트 작성 속도가 크게 빨라집니다. 작성한 마크다운이 실제로 어떻게 보이는지 확인하는 가장 빠른 방법은
미리보기 도구를 활용하는 것입니다.

마크다운 미리보기로 지금 바로 확인하기 →

관련 도구

글자수 세기 →: 원고 분량·SNS 글자수 제한 확인
텍스트 비교(Diff) →: 마크다운 문서 수정 전후 비교
CSV ↔ JSON 변환 →: 표 데이터를 마크다운 표로 변환 전 전처리