본문으로 바로가기
Markdown → HTML
실시간 미리보기는 정화 · 복사용 HTML은 원본.
블로그

마크다운을 HTML로 변환할 때 챙길 것 (2026)

마크다운을 HTML로 바꿀 때 표 변환부터 미리보기 정화와 raw 소스의 차이, 줄바꿈 함정까지 정리합니다.

정정 — 2026년 10월 14일: ~~취소선~~을 <del>old</del>로 바꾼다는 본문·이미지는 잘못됐습니다. 실제 결과는 <del>취소선</del>입니다. 가상의 도구 화면과 “30초 안전 변환” 문구가 든 카드 묶음도 이 글에서 내렸습니다. 변환 시간이나 게시 안전성을 보증하지 않으며, 아래에는 직접 대조할 입력·출력을 남깁니다.

README는 마크다운으로 잘 써놨는데, 이걸 회사 CMS나 이메일에 넣으려니 HTML이 필요합니다. 변환기에 붙여넣으면 끝일 것 같지만, 표가 깨지거나 줄이 엉뚱하게 붙고, 가끔은 남의 마크다운을 변환해 그대로 올렸다가 보안 사고가 납니다. 변환할 때 실제로 무엇을 챙겨야 하는지 정리합니다.

마크다운이 HTML로 어떻게 바뀌나

기본 문법이야 #이 제목, *가 강조로 바뀌는 것은 익숙합니다. 까다로운 건 표나 취소선 같은 확장 문법입니다.

PiPi Worlds 마크다운 변환 도구는 GitHub 스타일 마크다운(GFM)을 따릅니다. 표를 넣으면 <table>, <thead>, <td>로 펼쳐지고, ~~취소선~~은 <del>취소선</del>이 됩니다. 자동 링크도 지원합니다. GFM 문법 지원이 GitHub와 같은 화면을 보장하지는 않습니다. 복사 대상 CMS나 이메일의 CSS와 허용 태그에 따라 모양이 달라집니다.

같은 입력을 소스와 미리보기에서 대조하기

아래는 개인 정보가 없는 시험용 입력입니다. 변환 도구에 넣고 HTML 소스와 미리보기를 각각 확인하세요. 예시 주소는 연결이나 이미지 다운로드를 시험하라는 뜻이 아닙니다.

~~취소선~~

[안내](https://example.com/)

![예시](https://example.com/demo.png)

복사용 HTML 소스에는 다음 태그가 남습니다. 취소선 안의 글자는 다른 단어로 번역되거나 바뀌지 않습니다.

<p><del>취소선</del></p>
<p><a href="https://example.com/">안내</a></p>
<p><img src="https://example.com/demo.png" alt="예시"></p>

반면 미리보기에는 취소선이 그어진 취소선, 이동하지 않는 안내, 그림 대신 예시라는 글자가 보입니다. 미리보기에 링크나 이미지가 나타나지 않아도 복사용 소스에는 주소가 남습니다. 게시할 서비스에 소스를 넘기기 전에 그 주소와 허용 태그를 확인해야 합니다. 이 비교는 현재 도구의 출력 확인이지 게시처의 보안 검사나 모든 Markdown 문법의 검증이 아닙니다.

미리보기는 정화되고, 복사 소스는 원본이다

여기서 가장 중요한 구분이 나옵니다. 화면에 보이는 미리보기와 복사 버튼이 주는 HTML 소스는 다릅니다.

미리보기는 원본 HTML을 그대로 보여 주지 않습니다. 마크다운 이미지는 대체 텍스트로, 링크는 이동하지 않는 글자로 표시하고 raw HTML은 제외합니다. 이 서식 전용 변환 결과를 DOMPurify 허용 목록으로 처리합니다. 반면 복사용 HTML 소스는 가공 없는 변환 결과입니다. 예를 들어 Hi <img src=x onerror="alert(1)"> <script>alert(2)</script>를 변환하면, 소스에는 그 onerror와 <script>가 그대로 남아 있습니다. 이 차이를 모르면 위험합니다.

그래서 어디서 한 번 더 정화해야 하나

출처만으로 결정하지 마세요. 내가 쓴 문서라도 인용한 HTML 조각, 이미지 주소, 게시할 서비스의 규칙을 확인해야 합니다. 이 도구의 미리보기는 복사한 소스의 안전성 검사 결과가 아닙니다.

  • 코드로 설명할 때: CMS의 코드 블록 기능을 사용해 태그가 실행되는 HTML이 아니라 글자로 표시되는지 확인하세요.
  • 페이지로 표시할 때: 게시처가 허용하는 태그·속성·URL 정책으로 정화하세요. 다른 사람의 입력을 받는 서비스라면 게시 경로에서도 이 처리가 적용돼야 합니다.
  • 붙여 넣은 다음: 비공개 초안에서 표·줄바꿈·링크 목적지·이미지 주소를 확인하세요. 정화 뒤 다른 처리가 HTML을 바꾼다면 그 처리도 점검해야 합니다. DOMPurify는 정화 후 수정이 보호 효과를 무효화할 수 있다고 경고합니다.

예를 들어 ![예시](https://example.com/demo.png)를 입력하면 미리보기에는 그림 대신 예시라는 글자가 나타납니다. 하지만 HTML 소스에는 src 주소를 가진 이미지 태그가 남습니다. 이미지가 안 보인다고 주소까지 삭제된 것은 아닙니다. 설명용 주소이며 실제 이미지 다운로드나 게시처 보안을 시험한 예시는 아닙니다.

줄바꿈 한 번이 줄을 안 바꾸는 이유

자잘하지만 자주 당황하는 지점입니다. 마크다운에서 엔터를 한 번 쳤는데 HTML에서 줄이 안 바뀝니다.

표준 마크다운은 줄바꿈 한 번을 부드러운 줄바꿈(soft wrap)으로 봅니다. 줄1과 줄2를 엔터 하나로 나눠도 같은 <p> 문단 안에 이어집니다. 문단을 진짜로 나누려면 사이에 빈 줄을 넣어야 합니다. 한 문단 안에서 줄만 강제로 바꾸려면 줄 끝에 공백 두 칸을 두면 됩니다. 메일이나 CMS에서 줄 간격이 의도와 다르게 나온다면 대개 이 규칙 때문입니다.

그 마크다운, 어디서 변환하고 있나

마지막은 변환 장소 이야기입니다. 초안, 회의록, 비공개 명세를 HTML로 바꿀 때 그 텍스트가 어디론가 전송되는 도구라면, 공개 전의 내용이 외부 서버를 거치게 됩니다.

PiPi Worlds 마크다운 변환 도구는 이 변환 기능의 입력을 브라우저에서 처리하며 변환 요청을 자체 서버로 보내지 않습니다. 그러나 브라우저 확장 프로그램이나 복사한 HTML을 붙여넣는 서비스의 처리는 통제하지 못합니다. 실제 인증정보나 민감한 문서를 시험 입력으로 사용하지 말고, 실시간 미리보기로 결과를 확인한 뒤 정화 여부를 의식하며 소스를 복사하세요. HTML 안에 base64 데이터가 보이면 Base64 도구로, JSON 조각이 섞여 있으면 JSON 포맷터로 이어서 확인하면 됩니다.

자주 묻는 질문

마크다운의 표나 취소선도 HTML로 변환되나요?
네. GitHub 스타일 마크다운(GFM)을 따르므로 표는 `<table>`로, `~~취소선~~`은 `<del>`로 변환됩니다. 자동 링크도 지원합니다. 복사용 HTML 소스는 정화되지 않으므로 신뢰할 수 없는 입력은 게시 전에 다시 정화해야 합니다.
미리보기가 안전하다는 건 무슨 뜻인가요?
서식 확인용 미리보기입니다. 마크다운 이미지는 대체 텍스트로, 링크는 이동하지 않는 글자로 바꾸고 raw HTML은 별도 변환 경로에서 제외한 뒤 DOMPurify로 처리합니다. 게시 결과를 그대로 재현하거나 안전성을 인증하는 화면은 아닙니다. 다만 복사용 HTML 소스는 가공 없는 원본이므로, 신뢰할 수 없는 입력이라면 본인 서버에서 한 번 더 정화해야 합니다.
줄바꿈 한 번이 왜 줄을 안 바꾸나요?
표준 마크다운에서 줄바꿈 한 번은 부드러운 줄바꿈(soft wrap)이라 같은 문단으로 이어집니다. 문단을 나누려면 빈 줄을 넣고, 강제로 줄을 바꾸려면 줄 끝에 공백 두 칸을 두거나 빈 줄로 분리하세요.
마크다운 안에 raw HTML을 넣어도 되나요?
네. 복사용 소스에는 그 HTML이 그대로 통과합니다. 미리보기는 raw HTML을 제외하지만 복사용 소스 자체는 원본이라 신뢰할 수 없는 HTML을 그대로 게시하면 위험할 수 있습니다.
입력한 마크다운이 서버로 전송되나요?
이 변환 기능은 입력을 브라우저에서 처리하며 변환 요청을 자체 서버로 보내지 않습니다. 다만 브라우저 확장 프로그램이나 복사한 HTML을 붙여넣는 서비스의 처리는 통제할 수 없습니다. 실제 인증정보나 민감한 문서를 시험 입력으로 사용하지 마세요.

출처

검토 기록: Codex 코드·문구 검토 · 사람 보안 전문가 검토 아님

확인 내역과 한계 펼쳐 보기

2026-10-14에는 공개 한국어 카드 4장을 대조해 입력과 출력이 다른 취소선 예시 및 가상 화면의 안전·소요시간 주장을 철회했습니다. 새 본문 입력과 복사용 HTML을 실제 변환 함수로 대조했으며 Marked 공식 경고와 CommonMark 줄바꿈 규칙을 재확인했습니다. 앞선 코드 검토 범위는 다음과 같습니다. MarkdownHtml.jsx의 로컬 입력 상태와 markdownToHtml(input) 호출, 별도 markdownToPreviewHtml(input) 결과를 sanitizeMarkdownPreview로 처리하는 경로, MarkdownGuide.jsx의 확장 프로그램·복사 대상 경고를 대조했습니다. 모든 기기·브라우저 확장 동작을 계측하거나 비밀 입력의 안전성을 보증한 검토는 아닙니다.

이 글에서 더한 것 — 실제 MarkdownHtml.jsx와 markdown.js의 입력·출력 경로를 대조해 변환 요청 API가 없고 미리보기에만 DOMPurify가 적용됨을 확인했습니다. 브라우저 확장 프로그램과 복사 대상 서비스는 통제할 수 없다는 한계를 FAQ와 본문에 반영했습니다.

검토 기록은 기재된 확인 내역이며, 독립적인 정확성 보증은 아닙니다.

도구로 돌아가기 →