텍스트·데이터

마크다운 문법 정리: 제목·목록·링크·표 쓰는 법과 실수

다른 언어로 읽기: 日本語

마크다운 문법은 #, *, -, [ ]( ), | 같은 기호로 제목, 굵은 글씨, 목록, 링크, 표를 표시하는 글쓰기 규칙입니다. 줄 맨 앞에 ## 설치 방법이라고 쓰면 두 번째 단계 제목이 되고, **중요**라고 쓰면 굵은 글씨가 됩니다. 이렇게 쓴 글은 화면에 표시될 때 HTML로 바뀝니다. 그래서 기호마다 어떤 HTML 요소가 만들어지는지 알면 결과를 미리 예상할 수 있습니다.

깃허브 README, 기술 블로그, 개발 문서, 여러 노트 앱이 마크다운을 쓰지만 세부 규칙은 서비스마다 조금씩 다릅니다. 이 글은 표준 명세인 CommonMark와 깃허브가 쓰는 확장 문법(GFM, GitHub Flavored Markdown)을 기준으로 하고, 각 문법을 HTML 결과와 나란히 보여 줍니다.

마크다운이 적용되지 않는 경우는 대부분 세 가지 중 하나입니다. 엔터를 한 번만 쳐서 줄이 이어 붙은 경우, # 뒤에 공백을 빠뜨린 경우, 그리고 표나 체크박스처럼 해당 플랫폼이 지원하지 않는 확장 문법을 쓴 경우입니다.

마크다운 문법 한눈에 보기: 기호와 HTML 대응표

아래 표의 HTML 칸에는 태그 이름만 적었습니다. 예를 들어 h1은 여는 h1 태그와 닫는 h1 태그 사이에 제목 글자가 들어간다는 뜻이고, 변환 도구의 HTML 결과에서는 꺾쇠괄호로 감싼 태그로 보입니다. br, hr, img처럼 닫는 태그가 없는 요소는 변환기에 따라 끝에 슬래시를 붙이기도 하고 붙이지 않기도 하지만 의미는 같습니다.

하고 싶은 것 마크다운 만들어지는 HTML 요소
가장 큰 제목 # 제목 h1
3단계 제목 ### 제목 h3
굵게 **굵게** strong
기울임 *기울임* em
순서 없는 목록 - 항목 ul 안에 li
순서 있는 목록 1. 항목 ol 안에 li
링크 툴집 a (href="https://tooljip.com")
이미지 ! 바로 뒤에 로고를 붙여 씀 img (src="logo.png", alt="로고")
인용 > 인용문 blockquote 안에 p
인라인 코드 `npm install` code
코드 블록 백틱 세 개로 위아래를 감쌈 pre 안에 code
구분선 --- (앞에 빈 줄) hr
강제 줄바꿈 줄 끝에 공백 두 칸 br
문단 빈 줄로 나눈 글 덩어리 p

제목과 굵게·기울임 쓰는 법

제목은 # 개수로 1~6단계를 정합니다

#은 한 개부터 여섯 개까지 쓸 수 있고, 개수가 그대로 h1~h6이 됩니다. README 맨 위의 프로젝트 이름은 보통 # 하나로 써서 h1로 만들고, 그 아래 내용은 다음처럼 이어 갑니다.

## 설치 방법
### macOS에서 설치
#### Homebrew로 설치
h2 → 설치 방법
h3 → macOS에서 설치
h4 → Homebrew로 설치

글 제목을 h1으로 따로 보여 주는 블로그가 많아서, 블로그 본문 제목은 ##부터 시작하는 경우가 많습니다. 단계를 건너뛰지 않고(## 다음에 바로 ####를 쓰지 않고) 차례대로 쓰면 목차가 자연스럽게 만들어집니다.

한국어 문장에서는 밑줄 대신 별표를 씁니다

굵게는 **글자**나 __글자__, 기울임은 *글자*나 _글자_로 쓰고, 별표 세 개(***글자***)는 굵게와 기울임을 함께 적용합니다. 다만 한국어 문장에서는 밑줄(_)보다 별표가 안전합니다.

CommonMark는 단어 중간에 있는 밑줄을 강조 기호로 보지 않습니다. snake_case_name 같은 변수 이름이 기울임으로 바뀌지 않게 하려는 규칙입니다. 그런데 _기울임_을처럼 닫는 기호 바로 뒤에 조사가 붙으면 단어 중간으로 판단되어 기호가 그대로 보입니다. *기울임*을이라고 쓰면 정상적으로 적용됩니다.

별표에도 함정이 있습니다. **마크다운(Markdown)**은처럼 닫는 ** 바로 앞이 괄호나 따옴표 같은 문장부호이고 바로 뒤에 조사가 붙으면, CommonMark 규칙상 강조가 닫히지 않습니다. 이때는 **마크다운**(Markdown)은처럼 문장부호를 강조 밖으로 빼면 해결됩니다. 표준을 엄격하게 따르지 않는 변환기에서는 결과가 다를 수 있습니다.

또 이탤릭체가 따로 없는 한글 글꼴이 많습니다. 이 경우 브라우저가 글자를 기울여 흉내 내기 때문에, 한글 강조에는 기울임보다 굵게가 더 잘 보입니다.

순서 있는 목록과 순서 없는 목록 만들기

- 사과
- 배
  - 신고배
  - 원황배

1. 저장소를 복제합니다.
1. 패키지를 설치합니다.
1. 서버를 실행합니다.

변환 결과의 요소 구조는 다음과 같습니다. 하위 목록은 상위 li 안에 새 ul로 들어갑니다.

ul
├ li: 사과
└ li: 배
   └ ul
      ├ li: 신고배
      └ li: 원황배
ol
├ li: 저장소를 복제합니다.
├ li: 패키지를 설치합니다.
└ li: 서버를 실행합니다.

목록을 쓸 때 알아 둘 규칙은 다음과 같습니다.

  • 기호: -, *, +를 모두 쓸 수 있지만 한 목록 안에서는 하나로 통일합니다. 중간에 기호를 바꾸면 목록이 둘로 나뉩니다.
  • 번호: 실제 번호는 첫 숫자로만 정해집니다. 1.을 세 번 써도 1, 2, 3으로 표시되므로 항목을 끼워 넣을 때 번호를 다시 매길 필요가 없습니다. 3.으로 시작하면 ol 요소에 start="3" 속성이 붙어 3부터 셉니다.
  • 하위 목록: 상위 항목의 글자가 시작하는 위치만큼 들여씁니다. - 아래는 2칸, 1. 아래는 3칸입니다. 4칸을 요구하는 오래된 변환기도 있으니, 확실하지 않으면 4칸을 쓰는 편이 안전합니다.
  • 빈 줄: 목록 바로 앞에 빈 줄을 하나 두어야 앞 문단과 섞이지 않습니다.

날짜로 시작하는 줄이 목록으로 바뀌는 문제

한국식 날짜 표기인 2026. 11. 3. 정기 점검을 줄 맨 앞에 쓰면, 숫자와 마침표와 공백이 이어져 있어 2026번부터 시작하는 순서 있는 목록으로 처리됩니다. 뒤의 11. 3.까지 목록으로 겹쳐 처리되어 들여쓰기가 여러 단계로 보일 수 있습니다.

첫 마침표 앞에 역슬래시를 넣어 2026\. 11. 3. 정기 점검처럼 쓰면 줄 전체가 글자 그대로 표시됩니다. 첫 부분이 목록 기호가 아니게 되면 뒤의 11. 3.은 문장 중간이 되어 목록으로 해석되지 않기 때문입니다. 하이픈으로 시작하는 문장도 같은 원리로 목록이 되므로 \-로 막습니다.

링크·이미지·인용·코드 블록 쓰는 법

링크

보이는 글자 형식이며, 주소 뒤에 따옴표로 툴팁 제목을 붙일 수도 있습니다(예: 툴집). 툴팁 제목은 a 요소의 title 속성이 됩니다. README에서는 설치 안내처럼 저장소 안 파일을 상대 경로로 연결하는 경우가 많습니다.

주소에 공백이 있으면 링크가 끊어집니다. 문서처럼 공백을 %20으로 바꾸면 되고, CommonMark에서는 주소 전체를 꺾쇠괄호로 감싸는 방법도 허용합니다. 한글 주소가 어떻게 인코딩되는지는 URL 인코딩 도구로 확인할 수 있습니다.

이미지

링크 문법 바로 앞에 느낌표(!)를 붙이면 이미지가 됩니다. 대괄호 안의 글자는 img 요소의 alt(대체 텍스트)가 됩니다. 대체 텍스트는 이미지가 표시되지 않을 때나 화면 낭독기가 읽을 때 쓰이므로 비워 두지 않는 편이 좋습니다.

표준 마크다운에는 이미지 크기를 지정하는 문법이 없습니다. 그래서 사진 크기를 비율 유지하며 줄이는 법을 참고해 파일 자체를 알맞은 크기로 만들어 올리는 방법이 가장 확실합니다. 스크린숏은 PNG, 사진은 JPG나 WEBP처럼 용도에 맞는 이미지 형식을 고르면 저장소 용량도 아낄 수 있습니다.

인용과 코드

> 이 저장소는 학습용 예제입니다.

설치 전 `node -v`로 버전을 확인합니다.

```bash
npm install
```
blockquote
└ p: 이 저장소는 학습용 예제입니다.
p: 설치 전 [code: node -v]로 버전을 확인합니다.
pre
└ code (class="language-bash"): npm install

인용 안에서 문단을 나누려면 빈 줄에도 >를 붙이고, >>처럼 겹치면 인용 안의 인용이 됩니다. 코드 블록의 여는 백틱 뒤에 bash, python 같은 언어 이름을 쓰면 code 요소에 class="language-bash" 같은 속성이 붙습니다. 실제로 색을 입혀 보여 줄지는 플랫폼이 정합니다. 인라인 코드 안에 백틱 자체를 넣어야 한다면 바깥을 백틱 두 개로 감쌉니다.

마크다운 표 만드는 법과 정렬

| 항목 | 수량 | 가격 |
| :--- | :---: | ---: |
| 사과 | 3 | 4,500원 |
| 배 | 2 | 7,000원 |
table
├ thead
│ └ tr: th(왼쪽) 항목 / th(가운데) 수량 / th(오른쪽) 가격
└ tbody
   ├ tr: td 사과 / td 3 / td 4,500원
   └ tr: td 배 / td 2 / td 7,000원
  • 두 번째 줄의 구분 행은 반드시 있어야 하며, 첫 줄은 항상 머리글(th)이 됩니다.
  • 콜론의 위치로 정렬을 정합니다. :---는 왼쪽, :---:는 가운데, ---:는 오른쪽입니다. 금액처럼 자릿수를 비교하는 숫자는 오른쪽 정렬이 읽기 편합니다.
  • 원문에서 세로선 위치를 맞출 필요는 없습니다. 한글과 영문은 글자 폭이 달라 맞추기도 어렵고, 결과에도 영향이 없습니다.
  • 셀 안에 세로선을 넣으려면 \|로 씁니다. 셀 병합은 지원하지 않습니다.
  • 정렬이 align 속성으로 나올지 style 속성으로 나올지는 변환기마다 다릅니다.

마크다운이 적용되지 않을 때: 줄바꿈과 # 공백 실수

엔터를 한 번 치면 줄이 바뀌지 않는 이유

마크다운에서는 엔터를 한 번 쳐도 같은 문단으로 이어집니다. 원문을 보기 좋게 줄바꿈해 두어도 결과에는 영향이 없도록 만든 규칙입니다. 그래서 첫째 줄과 둘째 줄을 엔터 한 번으로 나누면 화면에는 "첫째 줄 둘째 줄"로 붙어 보입니다.

방법 입력 결과 HTML 주의할 점
엔터 한 번 줄 끝에서 Enter 같은 p 안, 공백처럼 표시 줄이 바뀌지 않음
빈 줄 Enter 두 번 p 두 개 문단 사이 간격이 생김
줄 끝 공백 두 칸 공백 2칸 후 Enter br 공백이 보이지 않고, 에디터 설정에 따라 저장할 때 지워질 수 있음
줄 끝 역슬래시 \ 후 Enter br CommonMark에서 지원하며, 오래된 변환기는 지원하지 않을 수 있음

문단을 나누려면 빈 줄을, 주소나 시처럼 문단 안에서 줄만 바꾸려면 공백 두 칸이나 역슬래시를 씁니다. 처리 방식은 플랫폼마다 다를 수 있습니다. 예를 들어 깃허브에서는 이슈나 댓글 입력창에서 엔터 한 번이 줄바꿈으로 표시되지만, 저장소의 .md 파일은 표준대로 처리됩니다.

# 뒤에 공백을 빠뜨리는 실수

CommonMark에서는 #제목이 제목이 되지 않고 글자 그대로 남습니다. # 뒤에 공백이 있어야 제목으로 인정됩니다. 이 덕분에 줄 맨 앞의 #맛집 같은 해시태그는 제목으로 바뀌지 않습니다. 공백 없이도 제목으로 처리하는 오래된 변환기가 있었기 때문에 "어디서는 되고 어디서는 안 된다"는 혼란이 생깁니다.

구분선이 제목으로 바뀌는 실수

글 바로 아랫줄에 ---를 쓰면 구분선이 아니라 윗줄을 h2로 만드는 문법으로 처리됩니다. 구분선을 넣으려면 --- 앞에 반드시 빈 줄을 둡니다.

표·체크박스는 어디서나 될까: 확장 문법 지원 차이

표, 체크박스, 취소선은 표준 CommonMark가 아니라 확장 문법입니다. 지원하지 않는 곳에 쓰면 표는 세로선과 하이픈이 한 문단으로 뭉쳐 보이고, 체크박스는 [ ]가 글자 그대로 남은 평범한 목록이 됩니다.

확장 문법 작성 예 GFM에서 만들어지는 HTML CommonMark 기본 깃허브(GFM)
표 세로선과 하이픈 구분 행 table, thead, tbody 미지원 지원
체크박스(작업 목록) - [ ] 할 일, - [x] 완료 li 안에 input type="checkbox" disabled="", 완료 항목은 checked="" 추가 미지원 지원
취소선 ~~취소~~ del 미지원 지원
주소 자동 링크 주소를 그대로 입력 a 꺾쇠괄호로 감쌀 때만 지원
각주 [^1]과 [^1]: 설명 본문에는 sup 안의 번호 링크, 글 끝에는 각주 목록 미지원 지원

이 밖의 블로그, 노트 앱, 협업 도구는 지원 범위가 서비스마다 다릅니다. 마크다운과 비슷하지만 다른 자체 문법을 쓰는 메신저도 있어서, 같은 별표 하나가 어떤 곳에서는 기울임으로, 어떤 곳에서는 굵게로 처리되기도 합니다. 처음 쓰는 서비스라면 해당 서비스의 도움말에서 지원 문법을 먼저 확인합니다.

변환 결과를 확인하는 순서

  1. 작성한 마크다운을 마크다운 HTML 변환 도구에 붙여 넣습니다.
  2. 실시간 미리보기에서 제목 단계와 목록 들여쓰기가 의도대로 나오는지 봅니다. 표나 체크박스 같은 확장 문법은 변환기가 지원하는 경우에만 표시되므로, 여기서 안 보인다고 해서 곧바로 문법 오류로 단정하지는 않습니다.
  3. 변환된 HTML에서 h2, br, table 같은 태그가 생겼는지 확인합니다. 줄바꿈 태그는 변환기에 따라 끝에 슬래시가 붙기도 합니다. 기본 문법을 썼는데 해당 태그가 없다면 그 부분이 인식되지 않은 것입니다.
  4. 문제가 있다면 앞에서 본 원인(# 뒤 공백, 빈 줄, 들여쓰기)을 고친 뒤 다시 변환합니다.
  5. 확장 문법은 변환기와 게시할 플랫폼의 지원 범위가 다를 수 있으니, 마지막으로 실제 플랫폼의 미리보기에서 한 번 더 확인합니다.

게시 전 마크다운 점검 체크리스트

  • 모든 # 뒤에 공백이 있고, 제목 단계를 건너뛰지 않았는가
  • 문단 사이에 빈 줄이 있고, 줄만 바꿀 곳에는 공백 두 칸이나 \를 넣었는가
  • 목록과 표 앞에 빈 줄이 있는가
  • 하위 목록 들여쓰기가 상위 항목의 글자 시작 위치와 맞는가
  • 한국어 강조에는 _ 대신 *를 썼고, 닫는 ** 앞에 괄호나 따옴표가 오지 않는가
  • 2026. 11. 3.처럼 숫자와 마침표로 시작하는 줄은 \.로 막았는가
  • 글 바로 아래에 ---를 붙여 쓰지 않았는가
  • 링크가 글자 형식이고, 주소에 공백이 없거나 %20으로 바꿨는가
  • 이미지마다 대체 텍스트를 넣었는가
  • 표, 체크박스, 취소선이 게시할 플랫폼에서 지원되는가

자주 묻는 질문

마크다운 파일 확장자는 .md와 .markdown 중 무엇을 써야 하나요?

둘 다 마크다운 파일 확장자로 쓰이며, 실제로는 짧은 .md가 훨씬 많이 쓰입니다. 깃허브 저장소의 README.md처럼 관례로 굳어진 이름도 .md를 씁니다. 어떤 확장자를 마크다운으로 인식해 표시할지는 서비스마다 다르므로, 특별한 이유가 없다면 .md를 쓰는 편이 무난합니다.

마크다운에서 글자 색이나 글자 크기를 바꿀 수 있나요?

표준 마크다운에는 글자 색이나 크기를 지정하는 문법이 없습니다. 크기는 제목 단계(#의 개수)로 간접적으로 조절할 수 있습니다. HTML 태그나 style 속성을 섞어 쓰는 방법도 있지만, 많은 플랫폼이 보안을 이유로 이런 속성을 걸러 내기 때문에 결과는 플랫폼마다 다릅니다.

마크다운 안에 HTML 태그를 섞어 써도 되나요?

CommonMark 명세는 원문에 HTML을 섞어 쓰는 것을 허용하므로, 변환기는 대개 HTML 태그를 그대로 출력합니다. 다만 게시 플랫폼이 보안을 위해 일부 태그나 속성을 제거할 수 있습니다. 또 HTML 블록 안에 쓴 마크다운 문법은 빈 줄로 구분하지 않으면 변환되지 않을 수 있습니다.

별표나 샵 같은 기호를 서식 없이 글자 그대로 보여 주려면 어떻게 하나요?

기호 앞에 역슬래시를 붙여 *, #, _, [처럼 쓰면 서식으로 처리되지 않고 글자 그대로 표시됩니다. 기호가 많이 섞인 명령어나 파일 경로는 백틱으로 감싸 인라인 코드로 만드는 방법이 더 간단합니다. 코드 안에서는 마크다운 문법이 적용되지 않습니다.

README.md 파일은 저장소의 어디에 두어야 깃허브 첫 화면에 보이나요?

가장 일반적인 위치는 저장소의 최상위 폴더입니다. 깃허브는 숨김 폴더인 .github나 docs 폴더에 있는 README도 인식해 표시하지만, 여러 곳에 있으면 그중 하나만 보이므로 한 곳에만 두는 편이 혼란이 적습니다. 자세한 우선순위는 깃허브 공식 도움말에서 확인할 수 있습니다.