마크다운(Markdown) 문법 총정리 📝 [헤더/리스트/코드블록/표/링크/이미지]

최근에 깃허브 README도 쓰고, 주피터 노트북 안에서 보고서를 쓰다보면 마크다운(Markdown)을 정말 자주 쓰게 된다. 근데 문법을 알아도 막상 "결과가 어떻게 나오지?" 싶을 때가 있어서 이번엔 문법과 렌더링 결과를 정리해봤다. 헤더부터 표, 코드블록, 링크, 이미지까지 자주 쓰는 마크다운 문법을 전부 정리해보았으니 도움이 되기를!

 

📌 바로가기

 

마크다운이란? 헤더 (Header) 텍스트 강조 (Bold / Italic / 취소선) 목록 (List) 링크 & 이미지 코드 (Code) 표 (Table) 인용구 (Blockquote) 수평선 & 줄바꿈 & 이스케이프 치트시트 (전체 요약)

 

---

 

1. 마크다운이란?

마크다운(Markdown)은 일반 텍스트에 간단한 기호를 붙여서 서식을 표현하는 경량 마크업 언어다. HTML처럼 복잡한 태그 없이도 제목, 굵기, 목록, 링크 등을 깔끔하게 표현할 수 있어서 개발자들 사이에서 특히 많이 쓰인다.

 

주로 쓰이는 곳은 이런 데들이다:

- 깃허브(GitHub) README.md 파일

- Jupyter Notebook, Jupyter Lab

- Notion, Obsidian 같은 노트 앱

- 개발 블로그, 기술 문서

 

파일 확장자는 .md 또는 .markdown을 쓴다. 이제 문법 하나씩 살펴보자.

 

Markdown 예시

 

 

2. 헤더 (Header)

# 기호의 개수로 제목의 크기를 정한다. # 하나가 가장 큰 제목(h1)이고 ###### 여섯 개까지 지원한다. # 뒤에 반드시 띄어쓰기를 해야 헤더로 인식된다는 점 주의.

문법	결과
# 제목 1	제목 1
## 제목 2	제목 2
### 제목 3	제목 3
#### 제목 4	제목 4
##### 제목 5	제목 5
###### 제목 6	제목 6

 

실제로 h1은 페이지 대제목, h2~h3는 섹션 구분, h4 이하는 잘 안 쓰는 편이다. README에서는 보통 ## 와 ### 조합을 가장 많이 쓴다.

 

 

3. 텍스트 강조 (Bold / Italic / 취소선)

텍스트에 굵기, 기울기, 취소선 효과를 줄 수 있다. 문법과 결과를 나란히 보면 바로 이해될 거다.

효과	문법	결과
굵게	**텍스트** 또는 __텍스트__	텍스트
기울임	*텍스트* 또는 _텍스트_	텍스트
굵게+기울임	***텍스트***	텍스트
취소선	~~텍스트~~	텍스트
인라인 코드	`텍스트`	텍스트

 

조합도 된다. 예를 들어 **~~취소선+굵게~~** 이렇게 쓰면 취소선+굵게 이렇게 나온다.

 

 

4. 목록 (List)

목록은 세 가지 종류가 있다. 순서 없는 목록, 순서 있는 목록, 체크박스 목록.

 

① 순서 없는 목록 (Unordered List)

문법	결과
- 사과 - 바나나 - 바나나 하위 항목 - 더 깊은 하위 항목 - 딸기	- 사과 - 바나나    ◦ 바나나 하위 항목       ▪ 더 깊은 하위 항목 - 딸기

 

들여쓰기는 스페이스 2칸 또는 4칸으로 한다. - 대신 *, + 써도 결과는 동일하다.

 

 

② 순서 있는 목록 (Ordered List)

문법	결과
1. 첫 번째 2. 두 번째 3. 세 번째 1. 하위 항목	1. 첫 번째 2. 두 번째 3. 세 번째    1. 하위 항목

 

재미있는 건 숫자를 1. 1. 1. 이렇게 다 1로 써도 렌더링하면 자동으로 1, 2, 3으로 바뀐다. 항목 순서 바꿀 때 숫자 일일이 안 고쳐도 된다는 장점이 있다.

 

 

③ 체크박스 목록 (Task List)

문법	결과
- [x] 블로그 글 작성 완료 - [x] 커밋 푸시 - [ ] PR 리뷰 요청 - [ ] 배포 확인	☑ 블로그 글 작성 완료 ☑ 커밋 푸시 ☐ PR 리뷰 요청 ☐ 배포 확인

 

체크박스는 GitHub 이슈, PR, 프로젝트 보드에서 특히 유용하다. - [x]는 완료, - [ ]는 미완료. 대괄호 안 띄어쓰기 빠뜨리면 안 된다.

 

GitHub issue page

 

 

5. 링크 & 이미지

링크와 이미지 문법은 구조가 거의 같다. 이미지는 맨 앞에 느낌표(!)만 추가하면 된다고 기억하면 쉽다.

 

① 링크

문법	결과
[구글](https://google.com)	구글
[구글](https://google.com "구글 홈페이지")	구글 (hover 시 툴팁 표시)
https://google.com	https://google.com (자동 링크)
<https://google.com>	https://google.com (꺾쇠 링크)

 

 

② 이미지

문법	설명
	기본 이미지 삽입. 이미지 로드 실패 시 대체텍스트 표시
	hover 시 툴팁 표시
[](링크URL)	이미지에 링크 걸기 (클릭 시 이동)

 

 

③ 참조형 링크

URL이 길거나 같은 링크를 여러 번 써야 할 때 유용하다. 본문에서 참조명을 쓰고, 링크 정의는 아래에 따로 모아서 관리할 수 있다.

문법	결과
[구글][google-link] [네이버][naver-link]	구글 네이버 (정의 부분은 렌더링 시 보이지 않음)

 

 

6. 코드 (Code)

코드를 표현하는 방법은 두 가지다. 문장 중간에 쓰는 인라인 코드와, 여러 줄을 묶는 코드 블록.

 

① 인라인 코드

문법	결과
`print("Hello")`를 실행하면	print("Hello")를 실행하면
변수 `count`에 1을 더한다	변수 count에 1을 더한다

 

 

② 코드 블록 (Fenced Code Block)

백틱 세 개(```) 뒤에 언어명을 붙이면 문법 강조(Syntax Highlighting)가 자동 적용된다.

문법	결과 (렌더링)
```python def hello(name): print(f"Hello, {name}!") hello("World") ```	def hello(name): print(f"Hello, {name}!") hello("World")
```bash git add . git commit -m "feat: 기능 추가" git push origin main ```	git add . git commit -m "feat: 기능 추가" git push origin main

 

자주 쓰는 언어 키워드는 이렇다: python, javascript, typescript, bash, sql, json, html, css, java, cpp 등.

 

GitHub README page

 

 

7. 표 (Table)

마크다운 표는 | 파이프와 - 하이픈으로 만든다. 두 번째 줄의 콜론(:) 위치로 정렬 방향을 지정할 수 있다.

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

 

정렬	문법	설명
왼쪽	:---	기본값 (생략 가능)
가운데	:---:	제목이나 상태값에 많이 씀
오른쪽	---:	숫자, 금액 표현에 유용

 

표 직접 짜는 게 귀찮으면 👉 Markdown Tables Generator 사이트 쓰면 된다.

 

 

8. 인용구 (Blockquote)

> 기호로 들여쓰기된 인용 블록을 만들 수 있다. 중첩도 가능하고, 인용구 안에 다른 마크다운 문법도 쓸 수 있다.

문법	결과
> 이것은 인용구입니다. > 두 번째 줄도 포함됩니다.	이것은 인용구입니다. 두 번째 줄도 포함됩니다.
> 외부 인용 >> 내부 중첩 인용 >>> 더 깊은 중첩	외부 인용 내부 중첩 인용 더 깊은 중첩
> **굵게**도 되고 > `코드`도 됩니다	굵게도 되고 코드도 됩니다

 

 

9. 수평선 & 줄바꿈 & 이스케이프

① 수평선 (Horizontal Rule)

문법	결과
--- 또는 *** 또는 ___

 

주의할 점: ---는 바로 위 줄에 텍스트가 있으면 h2 헤더로 인식된다. 수평선으로 쓰려면 위에 빈 줄을 하나 넣어줘야 함.

 

 

② 줄바꿈

마크다운에서 엔터 한 번은 줄바꿈이 아니다. 같은 문단으로 인식된다. 줄을 바꾸려면 아래 방법 중 하나를 써야 한다.

방법	문법	결과
문단 나누기	빈 줄 한 줄 삽입	문단이 분리됨 (간격 생김)
줄바꿈 (br)	문장 끝에 스페이스 2칸	줄만 바뀜 (간격 없음)
HTML 직접 사용	<br> 삽입	줄바꿈 (마크다운과 혼용 가능)

 

 

③ 이스케이프 (Escape)

마크다운 문법으로 쓰이는 기호를 그냥 텍스트로 출력하고 싶으면 앞에 \(백슬래시)를 붙이면 된다.

문법	결과
\*별표 그대로 출력\*	*별표 그대로 출력*
\# 해시 그대로 출력	# 해시 그대로 출력
\[대괄호\]	[대괄호]
\`백틱\`	`백틱`

 

이스케이프 가능한 문자: \ ` * _ { } [ ] ( ) # + - . !

 

 

10. 마크다운 치트시트 (전체 요약)

지금까지 다룬 내용 전체를 한 표로 정리했다. 이 표 하나만 북마크해도 충분하다 ㅎㅎ

기능	문법	결과 / 비고
h1 헤더	# 제목	제목
h2 헤더	## 제목	제목
h3 헤더	### 제목	제목
굵게	**텍스트**	텍스트
기울임	*텍스트*	텍스트
취소선	~~텍스트~~	텍스트
순서없는 목록	- 항목	• 항목 (*, + 도 가능)
순서있는 목록	1. 항목	1. 항목 (숫자 자동 정렬)
체크박스	- [x] / - [ ]	☑ / ☐
링크	[텍스트](URL)	텍스트
이미지		링크 앞에 ! 추가
인라인 코드	`코드`	코드
코드 블록	```언어명	문법 강조 적용됨
인용구	> 텍스트	텍스트
수평선	---	―――――――――
표	| 헤더 | 헤더 |	:---: 로 정렬 방향 지정
이스케이프	\기호	기호 앞에 \ 붙이기

 

 

+ 사용 예시

Jupyter Notebook 안에서 이렇게 코드 정리할 때에 유용하다.

(좌) 마크다운 코드, (우) 실행 결과

 

 

마크다운은 한 번 손에 익으면 HTML 없이도 빠르게 깔끔한 문서를 만들 수 있는 강력한 도구다. 특히 깃허브 README, 노션, 개발 블로그를 자주 쓴다면 오늘 정리한 내용 정도는 외워두는 게 확실히 생산성에 도움이 된다. (쓰다보면 손에 자연스럽게 익는다ㅎㅎ)