마크다운 문법은 제목, 목록, 링크 같은 기본은 어디서나 같지만, 줄바꿈 처리와 확장 문법은 서비스마다 다릅니다. 한국어 글에서는 **중요!**합니다처럼 문장 부호 바로 뒤에 조사가 붙으면 굵게가 풀리는 문제도 자주 겪습니다. 이 글은 마크다운 문법을 표로 정리하고, 각 문법을 실제로 HTML로 변환한 결과를 함께 보여 줍니다.

변환 결과는 2026-10-02에 확인했습니다. CommonMark와 GFM(GitHub Flavored Markdown) 결과는 이 사이트의 마크다운 미리보기와 같은 micromark 4와 GFM 확장으로 변환한 것이고, GitHub 결과는 GitHub Markdown API(POST /markdown)의 출력입니다. 기준 명세는 CommonMark 0.31.2와 GFM 0.29입니다.

마크다운 문법 정리 표

용도문법변환 결과
제목# 제목 ~ ###### 제목<h1> ~ <h6> (# 뒤에 공백 필수)
문단빈 줄로 구분<p>
강제 줄바꿈줄 끝에 공백 2개 또는 \<br />
굵게**굵게**<strong>
기울임*기울임*<em>
취소선~~취소~~<del> (GFM)
순서 없는 목록- 항목<ul><li>
순서 있는 목록1. 항목<ol><li>
체크박스- [ ] 할 일 / - [x] 완료비활성 체크박스 (GFM)
인라인 코드`code`<code>
코드 블록```js … ```<pre><code class="language-js">
링크[텍스트](https://example.com)<a href>
이미지![대체 텍스트](image.png)<img alt>
표| 열 |과 |---|<table> (GFM)
인용> 인용문<blockquote>
구분선---<hr />
각주본문[^1]과 [^1]: 설명문서 끝 각주 (GitHub)

제목·문단·줄바꿈

제목은 #의 개수로 단계를 정하고, # 뒤에 반드시 공백을 둡니다. #제목처럼 붙여 쓰면 그냥 문단이 됩니다. 네이버 블로그 사용자라면 이 차이가 익숙할 수 있습니다. 스마트에디터 ONE에서는 본문에 #태그명을 입력하면 태그로 추가되기 때문입니다(네이버 블로그 고객센터: 태그 입력 기능 안내).

줄바꿈은 서비스마다 가장 많이 다른 부분입니다. CommonMark에서 문단 안의 줄바꿈 한 번은 “소프트 줄바꿈”이라 브라우저에서 공백 하나로 보입니다. 첫 줄과 둘째 줄을 엔터 한 번으로 나눠 써도 첫 줄 둘째 줄처럼 한 줄로 이어집니다. 강제로 줄을 바꾸려면 줄 끝에 공백 두 개를 넣거나 첫 줄\처럼 역슬래시를 붙입니다.

입력CommonMark, GitHub .md 파일GitHub 이슈·댓글티스토리 마크다운 모드
엔터 한 번한 줄로 이어짐줄바꿈줄바꿈 (가이드 설명)
줄 끝 \줄바꿈줄바꿈줄바꿈

GitHub 문서에는 이슈, 풀 리퀘스트, 토론에서는 줄바꿈이 그대로 반영되고 .md 파일에서는 한 줄로 이어진다고 적혀 있습니다(GitHub Docs). Markdown API로도 확인했는데, markdown 모드에서는 <br>이 없고 댓글용 gfm 모드에서는 <br>이 들어갔습니다. 티스토리의 마크다운 가이드는 GFM 문법 덕분에 “별다른 방법없이 줄바꿈을 사용할 수 있게 되었습니다”라고 설명합니다(티스토리 글쓰기 가이드: 마크다운 문법). 티스토리에서 쓴 글을 GitHub README로 옮기면 문단이 한 줄로 합쳐질 수 있는 이유입니다. 어디서나 같은 결과를 원하면 줄 끝에 \를 쓰거나 문단 사이에 빈 줄을 넣으세요.

강조와 취소선: 한국어에서 굵게가 풀리는 경우

입력결과 (CommonMark·GitHub·마크다운 미리보기)
**굵게**는굵게 적용
**중요!**합니다**가 그대로 보임
**"인용"**은**가 그대로 보임
**10%**의 할인**가 그대로 보임
__강조__입니다__가 그대로 보임

한국어는 어절 사이를 띄어 쓰기 때문에 일본어나 중국어보다는 덜하지만, 문장 부호 바로 뒤에 조사가 붙으면 같은 문제가 생깁니다. 원인은 CommonMark의 “구분자 연속(delimiter run)” 규칙입니다(CommonMark 0.31.2 §6.2). 닫는 **는 오른쪽에 붙은(right-flanking) 구분자여야 하는데, 바로 앞이 문장 부호이면 바로 뒤가 공백이나 문장 부호여야 합니다. **중요!**합니다는 닫는 ** 앞이 !, 뒤가 합이라서 닫는 기호로 인정되지 않습니다. **굵게**는은 앞이 글자 게이므로 문제없습니다. GitHub Markdown API에서도 **중요!**합니다는 굵게가 되지 않았고 **굵게**는은 굵게가 되었습니다.

밑줄 두 개(__)는 또 다른 규칙에 걸립니다. _는 단어 중간에서 강조를 열거나 닫을 수 없는데, 한글 조사는 앞 글자에 붙어 있으므로 __강조__입니다는 굵게가 되지 않습니다. 한국어 글에서는 **를 쓰는 편이 안전합니다.

해결 방법은 세 가지입니다. 문장 부호를 ** 밖으로 빼서 **중요**!합니다로 쓰거나, 닫는 ** 뒤에 공백을 넣어 **중요!** 합니다로 쓰거나, 직접 운영하는 사이트라면 변환기에 CJK 대응 확장(micromark용 micromark-extension-cjk-friendly 등)을 넣습니다. 이 확장을 넣으면 위 표에서 풀리던 세 입력이 모두 굵게 변환되었습니다.

~~취소~~선 같은 취소선은 CommonMark에는 없고 GFM 확장입니다. GFM 명세는 물결표 한 개와 두 개를 모두 허용해서 GitHub와 마크다운 미리보기는 ~한 개~도 취소선으로 바꾸지만, 다른 변환기는 두 개만 받는 경우가 있으니 ~~를 쓰는 편이 안전합니다.

목록과 체크박스

1. 첫째
1. 둘째
1. 셋째

순서 있는 목록은 첫 숫자만 의미가 있고 나머지는 자동으로 번호가 매겨집니다. 위처럼 모두 1.로 써도 1, 2, 3으로 표시되므로 항목을 끼워 넣을 때 번호를 고칠 필요가 없습니다. 하위 목록은 부모 항목의 본문이 시작하는 위치까지 들여 써야 합니다. - 뒤의 본문은 세 번째 칸에서 시작하므로 - 세부 항목처럼 두 칸을 들여 쓰면 중첩되고, 한 칸만 들여 쓴 - 할 일 / - 세부 항목은 같은 단계의 항목 두 개가 됩니다. - [ ] 회의록 작성과 - [x] 일정 공유는 GFM 체크박스이고, 마크다운 미리보기에서는 클릭할 수 없는 표시용 체크박스로 나옵니다.

코드·링크·이미지·표

| 이름 | 금액 |
|---|---:|
| 커피 | 4,500원 |

표는 GFM 확장입니다. 두 번째 줄의 구분 행에서 :의 위치로 정렬을 정하며(:--- 왼쪽, :---: 가운데, ---: 오른쪽), 금액처럼 숫자 열은 오른쪽 정렬이 읽기 쉽습니다. 셀 안에 |를 쓰려면 \|로 이스케이프하고, 셀에는 인라인 요소만 들어갑니다. 표를 손으로 맞추기 번거로우면 마크다운 표 생성기에서 CSV나 JSON으로 만들 수 있습니다.

링크 주소에 공백이 있는 파일 이름은 [보고서](<2026 보고서.pdf>)처럼 < >로 감쌉니다. 변환 후에는 한글과 공백이 퍼센트 인코딩됩니다. 코드 블록은 여는 펜스 바로 뒤에 언어 이름을 쓰면 class="language-js"가 붙고, 색은 각 서비스의 하이라이터가 입힙니다. 마크다운 미리보기는 JavaScript, TypeScript, Python, Go, PHP, Ruby, Java, Bash, JSON, HTML, CSS, Markdown을 highlight.js로 강조합니다.

한글 제목의 앵커 주소

GitHub는 제목마다 앵커를 자동으로 만들어서 [설치 방법](#1-설치-방법)처럼 문서 안 링크를 걸 수 있게 합니다. GitHub 문서에 적힌 규칙은 영문자를 소문자로 바꾸고, 공백을 하이픈으로 바꾸고, 그 밖의 문장 부호는 지우고, 같은 앵커가 이미 있으면 -1, -2를 붙이는 것입니다(GitHub Docs: Section links). 한글은 그대로 남습니다. GitHub와 같은 규칙을 구현한 github-slugger 2.0.0으로 변환한 결과입니다.

제목앵커
## 마크다운 문법 정리!#마크다운-문법-정리
## 1. 설치 방법#1-설치-방법
## FAQ (자주 묻는 질문)#faq-자주-묻는-질문

!, ., 괄호가 사라지고 공백만 하이픈이 됩니다. 브라우저 주소창에서는 한글 앵커가 퍼센트 인코딩되어 보일 수 있지만 같은 주소입니다.

플랫폼별 차이: GitHub·티스토리·네이버 블로그·노션

항목GitHub티스토리네이버 블로그노션
마크다운 입력 방식.md 파일, 이슈·댓글에디터의 마크다운 모드고객센터의 스마트에디터 ONE 도움말에 마크다운 항목 없음입력 중 단축 문법을 블록으로 변환
기준 문법GFM + GitHub 확장GFM 기본 지원(100%는 아님)해당 없음노션 자체 단축키
> 입력인용인용해당 없음토글 목록
" 입력문자 그대로문자 그대로해당 없음인용 블록
취소선~~ 또는 ~GFM해당 없음~

출처: 티스토리 새 에디터 FAQ(“마크다운 문법은 Github Flavor Markdown (GFM)을 기본으로 지원합니다”), 티스토리 글쓰기 가이드(“100% 지원하는 것은 아닙니다”), 네이버 블로그 고객센터 스마트에디터 ONE(2026-10-02 목록 확인), Notion 도움말: Writing & editing basics.

티스토리는 에디터 상단에서 기본 모드, 마크다운 모드, HTML 모드를 전환할 수 있고, 공지에 따르면 기본 모드나 HTML 모드로 쓰던 글을 마크다운 모드로 바꾸면 글 모양이 의도하지 않게 바뀔 수 있습니다(티스토리: 마크다운, HTML모드 사용하기). 노션은 마크다운 파일을 보여 주는 서비스가 아니라, 입력하는 동안 **로 굵게, ~로 취소선, []로 체크박스, >와 공백으로 토글 목록, "와 공백으로 인용 블록을 만드는 블록 에디터입니다. GitHub식 > 인용을 노션에 입력하면 인용이 아니라 토글 목록이 되므로 주의하세요.

GitHub 전용 문법도 있습니다. > [!NOTE] 같은 알림 상자, ```mermaid 다이어그램, $…$ 수식(MathJax), :tada: 같은 이모지 단축 코드, @사용자 멘션, #26 같은 이슈 참조입니다(GitHub Docs의 각 문서). 다른 곳에서는 대부분 글자 그대로 보이며, 마크다운 미리보기에서도 아래 입력은 [!NOTE]로 시작하는 평범한 인용이 됩니다.

> [!NOTE]
> 참고 사항입니다.

각주 본문[^1]과 [^1]: 설명은 GitHub와 마크다운 미리보기에서 문서 끝의 각주 목록으로 변환됩니다.

HTML 태그와 보안

CommonMark 명세는 HTML 태그를 그대로 통과시키지만, 실제로 보이는지는 서비스에 달려 있습니다.

입력GitHub마크다운 미리보기
<details><summary>더 보기</summary>접기 상자로 표시글자로 표시
<script>alert(1)</script>글자로 표시글자로 표시
<b onclick="x()"><b>만 남고 onclick 삭제글자로 표시

GFM에는 <script>, <style>, <iframe> 등 9가지 태그를 막는 규칙이 있고(GFM §6.11), GitHub는 속성까지 걸러 냅니다. 마크다운 미리보기는 붙여 넣은 글에서 스크립트가 실행되지 않도록 모든 HTML 태그를 글자로 표시합니다. 태그 사이의 마크다운(위 예의 내용)은 그대로 변환됩니다. <details> 접기 상자는 GitHub에서 확인하세요.

작성한 마크다운 확인하기

  1. 마크다운 미리보기에 붙여 넣어 CommonMark·GFM 기준의 결과를 봅니다. **가 그대로 남아 있으면 앞에서 설명한 문장 부호 문제입니다.
  2. 마크다운 린터로 검사합니다. markdownlint 0.40의 기본 규칙으로 제목 단계 건너뛰기, URL 직접 입력 같은 문제를 줄 번호와 함께 알려 줍니다.
# 릴리스 노트

https://example.com 참고

### 수정 사항

* 첫째
- 둘째

이 문서에서는 3번째 줄에 MD034(URL 직접 입력), 5번째 줄에 MD001(h1에서 h3로 건너뜀), 8번째 줄에 MD004(목록 기호 혼용), 7번째와 8번째 줄에 MD032(목록 앞뒤에 빈 줄 없음)가 나옵니다. 마지막 지적은 *와 -가 서로 다른 목록으로 해석되었다는 뜻입니다.

  1. 알림 상자, Mermaid, 수식, <details>처럼 GitHub에서만 동작하는 문법은 GitHub의 미리보기 탭에서 확인합니다.