마크다운 문법 — md 파일이 기호투성이로 보이는 이유, 엔터가 줄바꿈이 안 될 때, HTML로 바꾸기

=제목·표 칸 수·태그 제거 뒤 공백·두 칸 들여쓰기 범위 · 문구 3 그림 예시·인용 표현·노션) 전건 반영. javascript: 링크·onerror·글 밑 ---·칸 모자란 표는 직접 재실측(알림창 0).

인터넷에서 받은 프로그램 폴더의 README.md, 노트 앱에서 내보낸 파일을 예전 메모장으로 열면 줄 앞에 #이 붙어 있고 단어 양옆을 별표 두 개가 감싸고 있습니다. 파일이 깨진 게 아닙니다. 마크다운(Markdown)이라는 글쓰기 규칙으로 쓴 글입니다.

마크다운을 HTML로 바로 바꾸기 →

마크다운은 존 그루버가 2004년에 공개한 표기법입니다. 그가 밝힌 취지는 태그를 붙인 티가 나지 않고 텍스트 그대로 읽히는 글을 쓰자는 것이었습니다(Daring Fireball). 그래서 기호 몇 개만 알면 메모장에서도 쓸 수 있고, 변환기에 넣으면 웹페이지에 쓰는 HTML이 됩니다. 아래 결과는 모두 Tooly 마크다운 변환기에 직접 넣어 나온 것입니다.

기호가 HTML로 바뀌는 모습

이 변환기와 GitHub에서는 목록을 두 칸만 들여 써도 안쪽 목록이 됩니다. - 사과 아랫줄에 빈칸 두 개를 띄우고 - 부사를 쓰면 사과 항목 안에 부사 목록이 생깁니다. 네 칸을 요구하는 변환기도 있으니, 다른 곳에서 안 되면 네 칸을 띄우세요. 번호 목록을 3번부터 쓰면 <ol start="3">이 되어 3부터 셉니다.

헷갈리기 쉬운 세 가지도 확인했습니다. #해시태그처럼 #과 글자 사이에 빈칸이 없으면 제목이 되지 않고 그냥 문장으로 남습니다. snake_case_word처럼 낱말 가운데 낀 밑줄은 기울임으로 바뀌지 않습니다. 가로줄 ---는 위아래를 빈 줄로 띄워야 합니다. 글 바로 아랫줄에 붙여 쓰면 가로줄 대신 윗줄이 제목(<h2>)이 됩니다.

엔터 한 번은 줄바꿈이 아닙니다

마크다운에서 가장 많이 막히는 곳입니다. 아래처럼 쓰고 변환하면 두 줄이 한 줄로 붙습니다.

첫째 줄
둘째 줄

결과는 <p>첫째 줄 둘째 줄</p>입니다. 널리 쓰이는 마크다운 명세인 CommonMark 규칙에서 엔터 한 번은 "부드러운 줄바꿈"이라 웹 화면에서는 띄어쓰기 한 칸이 됩니다(CommonMark 0.31.2). 줄을 나누는 방법은 셋입니다.

1. 빈 줄을 한 줄 넣기 — 문단이 둘로 나뉩니다(<p> 두 개).
2. 줄 끝에 빈칸 두 개 — 같은 문단 안에서 줄만 바뀝니다(<br />). 눈에 안 보이는 빈칸이라 다른 사람이 고치다가 지우기 쉽습니다.
3. <br> 태그 쓰기 — 그대로 HTML 줄바꿈으로 남습니다.

CommonMark와 GitHub는 줄 끝 역슬래시(\)도 줄바꿈으로 받아 줍니다. Tooly 변환기에서는 역슬래시가 글자로 그대로 남으니, 이 도구에서는 빈칸 두 개나 <br>을 쓰세요.

GitHub 안에서도 장소마다 다릅니다. GitHub 공식 문서에 따르면 이슈·풀 리퀘스트·토론 댓글에서는 엔터 한 번이 그대로 줄바꿈이 되지만, 저장소의 .md 파일에서는 한 줄로 붙습니다(GitHub 문서). 댓글에서 쓰던 습관 그대로 README를 쓰면 줄이 다 붙어 보이는 이유입니다.

표는 둘째 줄이 있어야 만들어집니다

| 이름 | 수량 |
|---|---:|
| 사과 | 3 |

둘째 줄의 |---| 구분 줄이 표의 머리와 몸을 나눕니다. 이 줄을 빼면 표가 되지 않고, 세로 막대 기호가 섞인 문장 한 줄로 나옵니다. 구분 줄에 콜론을 붙이면 정렬이 정해집니다. ---:는 오른쪽 정렬이라 숫자 열에 맞고, :---:는 가운데 정렬입니다. 변환하면 <th style="text-align:right;">처럼 정렬이 HTML에 그대로 들어갑니다.

같은 글이 앱마다 다르게 보이는 이유

2004년 원래 마크다운에는 표가 없었습니다. 표·체크 목록·취소선은 나중에 붙은 확장 문법이라, CommonMark 기본 규칙에도 들어 있지 않습니다. GitHub처럼 확장을 받아들인 곳에서는 보이고, 기본 규칙만 따르는 곳에서는 기호가 그대로 남습니다.

Tooly 변환기가 받아들이는 것과 아닌 것은 이렇습니다.

md 파일을 읽기 좋게 여는 곳

md 파일은 그냥 글자 파일이라 어떤 편집기로든 열립니다. 문제는 기호가 그대로 보인다는 점인데, 다음 프로그램은 서식을 입혀서 보여 줍니다.

• VS Code — md 파일을 열고 Ctrl+Shift+V(맥은 Shift+Cmd+V)를 누르면 미리 보기가 열립니다. Ctrl+K를 누른 뒤 V를 누르면 옆 칸에 나란히 띄웁니다(VS Code 문서).
• 옵시디언 — 노트를 마크다운 글자 파일로 보관함(vault)에 저장하는 노트 앱입니다. 보관함은 내 컴퓨터의 폴더이고, 바깥에서 파일이 바뀌어도 옵시디언이 알아서 새로 고칩니다(옵시디언 도움말). 받은 md 파일을 보관함 폴더에 넣으면 노트로 열립니다.
• 노션 — 데스크톱 앱에서 md 파일을 오른쪽 클릭해 연결 프로그램으로 노션을 고르면 읽기 전용 미리 보기로 열립니다(한 번에 10개까지). 페이지로 들여오려면 설정의 가져오기(Import)에서 텍스트·마크다운을 고릅니다. 가져오기는 데스크톱과 웹에서만 됩니다(노션 도움말).
• GitHub — 저장소에 올린 README.md는 자동으로 서식이 입혀져 보입니다.
• 윈도 메모장 — 마이크로소프트가 2025년 5월 윈도 인사이더 미리 보기부터 메모장에 마크다운 서식 보기를 넣기 시작해 차례로 넓혀 왔습니다(윈도 인사이더 블로그). 메모장 판이나 서식 설정에 따라 기호가 그대로 보일 수 있습니다.

HTML로 바꿔 쓰는 순서

웹페이지나 블로그 편집기의 HTML 칸에 넣을 코드가 필요할 때 씁니다.

1. 위쪽 여기에 마크다운을 입력하세요 칸에 마크다운을 붙여 넣습니다.
2. HTML로 변환을 누릅니다.
3. 아래 칸에 줄 맞춤이 된 HTML 코드가 나옵니다. 복사를 눌러 가져갑니다.

결과 칸은 미리 보기가 아니라 HTML 코드입니다. 화면 모양을 보고 싶다면 복사한 코드를 메모장에 붙여 .html 파일로 저장한 뒤 브라우저로 열면 됩니다. 반대로 웹페이지의 HTML을 마크다운으로 되돌리려면 HTML → 마크다운 변환을 쓰면 됩니다.

남이 준 마크다운을 내 사이트에 그대로 붙일 때는 한 가지를 확인하세요. 변환기는 위험한 코드를 걸러 주지 않습니다. 마크다운 안에 섞인 <script> 태그, <img src="x" onerror="…">처럼 on으로 시작하는 속성이 결과에 그대로 들어갔고, HTML이 하나도 없는 마크다운 링크 [눌러](javascript:…)도 javascript: 주소를 단 링크로 바뀌었습니다(도구 결과 칸은 글자로만 보여 주므로 실행되지는 않습니다). 출처를 모르는 글이라면 결과에 <script>, on으로 시작하는 속성(onclick·onerror 같은 것), javascript:로 시작하는 주소가 없는지 보고 올리세요.

자주 묻는 질문

md 파일이 뭔가요?
마크다운으로 쓴 글을 담은 텍스트 파일입니다. 확장자가 .md나 .markdown이고, 메모장으로도 열립니다.

엔터를 쳤는데 줄이 안 바뀌어요.
README 같은 md 파일과 이 변환기에서는 엔터 한 번이 띄어쓰기로 바뀝니다. 빈 줄을 넣어 문단을 나누거나, 줄 끝에 빈칸 두 개를 넣거나, <br>을 쓰세요. GitHub 댓글처럼 엔터 한 번을 그대로 줄바꿈으로 보여 주는 곳도 있어서 앱마다 다릅니다.

표를 만들었는데 글자로 나와요.
둘째 줄에 |---|---| 같은 구분 줄이 있는지 보세요. 이 변환기는 구분 칸이 머리 줄보다 모자라도 표로 만들지만, GitHub 명세는 칸 수가 같아야 표로 인정합니다(GFM 명세). 머리 줄 칸 수에 맞춰 두면 어디서나 표가 됩니다.

#을 썼는데 제목이 안 돼요.
# 제목처럼 # 뒤에 빈칸이 있어야 제목이 됩니다. #제목은 문장으로 남습니다.

기호를 뺀 글자 수만 세고 싶어요.
마크다운 원문을 그대로 세면 #이나 별표까지 글자로 들어갑니다. HTML로 바꾼 뒤 HTML 태그 제거에 넣으면 기호와 태그는 빠집니다. 다만 변환 결과의 줄 맞춤 빈칸과 빈 줄이 남아 공백 포함 글자 수가 크게 늘어나니, 공백을 뺀 글자 수로 보세요. 공백 포함·제외 기준은 글자 수 세기에 정리해 두었습니다.

변환 결과는 2026년 10월 7일 Tooly 마크다운 → HTML 변환기에서 직접 확인한 값입니다.