마크다운 미리보기

마크다운이란?

마크다운(Markdown)은 2004년 존 그루버(John Gruber)가 애런 스워츠 등과 함께 만든, 일반 텍스트에 간단한 기호를 붙여 서식을 표현하는 방식입니다. 「# 제목」이라고 쓰면 제목, 「**굵게**」라고 쓰면 굵은 글씨가 됩니다. 변환하지 않은 원문도 읽기 쉽다는 것이 설계 목표였고, 그래서 개발자 문서(README), 블로그, 노트 앱, 위키, 채팅 도구에서 널리 쓰입니다. 편집기 없이 키보드만으로 쓸 수 있고, 텍스트 파일이라 버전 관리와 비교가 쉽다는 점이 장점입니다.

이 미리보기가 지원하는 문법

아래 표는 이 도구가 변환하는 문법입니다. 오른쪽 입력창에 그대로 붙여 넣어 결과를 확인해 보세요.

CommonMark, GFM, 그리고 원조 마크다운

원조 마크다운 설명서는 모호한 부분이 많아 구현마다 결과가 달랐습니다. 이를 해결하려고 만든 표준 명세가 CommonMark이고, 이 글을 쓰는 시점의 최신 버전은 0.31.2(2024년 1월 28일)입니다. GitHub가 쓰는 GFM(GitHub Flavored Markdown)은 CommonMark를 기반으로 확장 문법을 얹은 것으로, 대표적인 확장은 다음과 같습니다.

• 표(table): 파이프(|)와 구분선 행으로 만듭니다. 원조 마크다운에는 없던 문법입니다.
• 체크리스트(task list): - [ ], - [x].
• 취소선(strikethrough): ~~텍스트~~.
• 자동 링크(autolink): 주소만 써도 링크로 바뀝니다.
• 일부 HTML 태그 필터링: script, iframe, style 같은 위험한 태그가 원문 HTML에 있으면 무력화합니다.

이 도구는 위 확장 중 표·체크리스트·취소선·자동 링크를 지원합니다. 대신 각주, 정의 목록, 수식, 다이어그램(Mermaid), 참조 링크([글][1]) 같은 문법은 렌더러마다 지원이 다른 영역이라 변환하지 않습니다.

렌더러마다 결과가 달라지는 지점

같은 마크다운이 GitHub, 블로그 플랫폼, 노트 앱에서 다르게 보이는 경우는 대개 다음 중 하나입니다.

• 줄바꿈: CommonMark에서는 줄 하나를 바꿔도 같은 문단으로 이어지고, 줄 끝에 공백 2칸 이상(또는 백슬래시)을 넣어야 <br>가 됩니다. 일부 댓글·채팅 환경은 줄바꿈을 그대로 살립니다. 이 도구의 「줄바꿈을 그대로 <br>로」 옵션이 이 차이를 재현합니다.
• 원문 HTML: 대부분의 렌더러가 마크다운 안의 HTML을 허용하지만 어떤 태그와 속성을 남길지는 제각각입니다. 이 도구는 안전을 위해 모두 문자 그대로 보여줍니다.
• 목록 들여쓰기: 중첩 목록에 필요한 공백 수(2칸, 4칸)가 구현마다 다릅니다. 번호 목록은 마커 너비에 맞춰 3칸 이상 들여쓰는 편이 안전합니다.
• 제목 공백: #제목처럼 공백이 없으면 제목이 아닌 렌더러가 많습니다. 항상 # 제목으로 쓰세요.
• 표의 열 수: 머리글 행과 구분선 행의 열 수가 다르면 표로 인식되지 않습니다.

검산 예시

예시 1. 정렬이 있는 표: 아래 입력은 머리글 2열, 구분선 행 :--(왼쪽)과 --:(오른쪽), 데이터 2행입니다. 변환 결과의 th와 td에 열마다 text-align이 붙고, 데이터 행은 2개가 됩니다.

| 이름 | 점수 |
|:--|--:|
| 가 | 90 |
| 나 | 85 |

<table>
<thead><tr><th style="text-align:left">이름</th><th style="text-align:right">점수</th></tr></thead>
<tbody>
<tr><td style="text-align:left">가</td><td style="text-align:right">90</td></tr>
<tr><td style="text-align:left">나</td><td style="text-align:right">85</td></tr>
</tbody></table>

예시 2. 중첩 목록: 「사과」「배」를 2칸 들여쓰면 「과일」 항목 안의 하위 ul이 됩니다. 최상위 항목은 2개, 하위 항목은 2개입니다.

- 과일
  - 사과
  - 배
- 채소

<ul>
<li>과일
<ul>
<li>사과</li>
<li>배</li>
</ul></li>
<li>채소</li>
</ul>

마크다운과 보안: 변환된 HTML을 믿으면 안 되는 이유

마크다운은 설계상 원문에 HTML을 섞어 쓸 수 있습니다. 그래서 사용자가 입력한 마크다운을 그대로 HTML로 변환해 페이지에 넣는 것은 XSS(교차 사이트 스크립팅) 취약점이 되기 쉽습니다. 전형적인 공격은 세 가지입니다.

• 스크립트 태그와 이벤트 속성: <img src=x onerror=…>처럼 태그의 이벤트 속성에 코드를 넣습니다.
• 위험한 주소: [클릭](javascript:…)처럼 링크 주소에 javascript: 스킴을 넣습니다.
• 속성 탈출: 링크 주소에 따옴표를 넣어 href 속성을 닫고 새 속성(onmouseover 등)을 끼워 넣습니다.

이 도구는 세 가지에 모두 대응합니다. 입력의 <, >, 따옴표를 먼저 문자로 바꿔 원문 HTML을 실행하지 않고, 링크·이미지 주소는 http, https, mailto, tel, 상대 경로, 앵커만 허용하며 나머지는 #로 대체합니다(제어 문자를 섞은 우회도 제거). 외부 링크에는 rel="noopener noreferrer nofollow"를 붙입니다. 「보안 테스트 샘플」 버튼으로 직접 확인할 수 있습니다.

다만 이 변환기는 학습·미리보기용입니다. 직접 만든 정규식 변환기는 예상하지 못한 조합에서 뚫릴 수 있으므로, 실제 서비스에서 사용자 입력을 렌더링한다면 검증된 마크다운 라이브러리와 HTML 살균(sanitize) 라이브러리를 함께 쓰고, 가능하면 콘텐츠 보안 정책(CSP)도 설정하세요. 복사한 HTML을 다른 사이트의 편집기에 붙여 넣을 때도 출처가 불분명한 마크다운은 먼저 소스를 확인하는 습관이 필요합니다.

흔한 실수

• 목록 앞에 빈 줄이 없음: 문단 바로 아래 목록을 붙여 쓰면 일부 렌더러는 목록으로 인식하지 못합니다. 문단과 목록 사이에 빈 줄을 두세요.
• 코드 블록 백틱 개수 불일치: 열 때 3개, 닫을 때 2개를 쓰면 뒤의 문서 전체가 코드로 보입니다. 코드 안에 백틱 3개가 있다면 바깥을 4개로 감쌉니다.
• 별표·밑줄이 의도치 않게 서식으로 변함: 수식이나 파일명의 *, _는 백슬래시로 이스케이프(\*)하세요.
• 링크 주소에 공백·괄호: 공백은 %20으로 바꾸고, 괄호가 한 쌍으로 들어간 주소는 허용되지만 짝이 맞지 않는 괄호는 피하세요.
• 이미지 설명 누락: ![](주소)처럼 대체 텍스트를 비우면 스크린리더 사용자와 이미지가 로드되지 않는 환경에서 정보가 사라집니다.

한계와 이 도구를 쓰면 안 되는 경우

이 도구는 핵심 문법과 GFM 일부를 다루는 간이 변환기이며 CommonMark 전체 명세를 통과하지 않습니다. 참조 링크, 각주, 정의 목록, 수식, 원문 HTML 블록, 들여쓰기 코드 블록, 복잡한 목록 안 코드 블록은 처리하지 않거나 결과가 다를 수 있습니다. 이미지는 외부 주소를 불러오면 해당 서버에 접속 기록이 남을 수 있습니다. 최종 게시 전에는 사용하는 플랫폼(GitHub, 블로그, 노트 앱)의 미리보기에서 한 번 더 확인하세요. 비밀번호·개인정보 같은 민감한 내용은 어떤 온라인 도구에도 입력하지 않는 것이 원칙입니다(이 도구는 서버로 전송하지 않지만 습관의 문제입니다).

결과를 활용하는 방법

1. 문서를 왼쪽에 작성하며 제목 계층(h1 → h2 → h3)이 건너뛰지 않았는지 확인합니다.
2. 「HTML 소스」 탭에서 변환 결과를 보고 필요하면 「HTML 복사」로 가져갑니다. 다른 사이트에 게시할 때는 그 플랫폼의 살균 규칙이 적용된다는 점을 알아 두세요.
3. README나 위키에 올릴 문서는 대상 플랫폼의 렌더러에서 표, 체크리스트, 줄바꿈이 같은지 최종 확인합니다.
4. 분량 제한이 있는 글은 글자수 & 단어수 세기로 길이를 점검합니다.
5. HTML만 필요하고 태그를 제거하고 싶다면 HTML 태그 제거 도구, 두 버전의 차이를 보려면 텍스트 비교 도구, 목업용 본문이 필요하면 더미 텍스트 생성기를 이용하세요.

자주 묻는 질문