마크다운(Markdown)으로 작성한 메모를 마크다운을 지원하지 않는 블로그에 붙여넣고 싶거나, HTML 이메일 템플릿에 본문 내용을 넣고 싶을 때, 혹은 사내 CMS의 WYSIWYG 에디터에 HTML 형태로 가져가야 할 때가 있습니다. 이러한 상황에서는 마크다운을 HTML로 변환하는 작업이 필요합니다.
로컬 환경에서 Pandoc 같은 도구나 빌드 스크립트를 실행하는 방법도 있지만, 단순한 변환을 위해 매번 터미널 명령어를 입력하는 것은 번거롭습니다. 또한 비공개 초안이나 사내 문서를 외부 온라인 서비스에 붙여넣는 것은 보안상 꺼려지기 마련입니다. 이 글에서는 마크다운과 HTML의 관계를 짚어보고, 브라우저 안에서 안전하게 끝내는 변환 방법과 실무에서 자주 쓰이는 라이브러리 및 도구를 비교해 정리합니다.
바로 변환하고 싶을 때
Markdown to HTML 변환기에 마크다운을 붙여넣고 실행 버튼을 누르면 즉시 HTML 코드가 생성됩니다. 별도의 설치 과정이 필요 없으며, 모든 처리가 브라우저 내부에서만 이루어지므로 데이터가 외부 서버로 전송되지 않습니다.
이 도구에서 다루는 변환은 CommonMark새 탭에서 열립니다를 기본 문법 사양으로 따르며, 표, 작업 목록(체크박스), 취소선, 자동 링크 등의 확장 기능은 GitHub Flavored Markdown(GFM) 사양새 탭에서 열립니다을 준수합니다. 두 사양의 차이는 CommonMark와 GFM의 차이에서 자세히 정리하고 있습니다.
마크다운과 HTML의 관계
마크다운은 사람이 읽고 쓰기 쉬운 형태를 지향하는 가벼운 마크업 언어(lightweight markup language)입니다. 반면 HTML은 웹 브라우저가 화면을 렌더링하기 위한 구조화된 언어로, 태그를 사용해 각 요소를 감쌉니다. 예를 들어 다음과 같은 마크다운 문장은,
# 제목
이것은 **굵은 글씨**와 _기울임꼴_을 포함한 문단입니다.
- 항목 1
- 항목 2
HTML로 변환하면 다음과 같은 구조가 됩니다.
<h1>제목</h1>
<p>이것은 <strong>굵은 글씨</strong>와 <em>기울임꼴</em>을 포함한 문단입니다.</p>
<ul>
<li>항목 1</li>
<li>항목 2</li>
</ul>
마크다운은 애초에 HTML 출력을 전제로 설계되었기 때문에, 두 형식 사이의 문법과 태그 대응 관계는 거의 1 대 1로 일치합니다.
마크다운을 HTML로 변환해야 하는 상황
마크다운을 직접 지원하지 않는 블로그 및 CMS
WordPress의 기본 클래식 에디터나 일부 사내 CMS의 WYSIWYG 에디터는 마크다운을 직접 인식하지 못하고 HTML 입력을 요구합니다. 마크다운으로 초안을 작성한 뒤 HTML로 변환해 붙여넣으면 원하는 레이아웃과 서식을 그대로 반영할 수 있습니다.
HTML 이메일 본문 작성
뉴스레터 발송 서비스나 마케팅 이메일 템플릿에 본문을 삽입할 때 마크다운으로 초안을 작성하면 가독성을 유지하면서 빠르게 글을 쓸 수 있습니다. 작성이 끝난 후 최종적으로 HTML로 변환해 템플릿에 넣으면 서식이 깔끔하게 적용됩니다.
정적 사이트 및 문서 빌드 파이프라인
일부 정적 사이트 생성기나 사내 문서화 도구 중에는 마크다운 파서를 내장하지 않고 빌드 단계에서 사전 렌더링된 HTML 파일만을 입력으로 받는 경우가 있습니다. 이 경우 빌드 파이프라인의 한 단계로 마크다운을 HTML로 변환하는 처리가 필요합니다.
FormatArc로 변환하기
Markdown to HTML 도구는 텍스트를 붙여넣고 버튼을 누르는 것만으로 HTML을 생성합니다.
1단계: 도구 열기
Markdown to HTML 페이지로 이동합니다.
2단계: 마크다운 붙여넣기
왼쪽 에디터 영역에 변환할 마크다운 텍스트를 붙여넣습니다. 제목, 목록, 링크, 이미지, 코드 블록 등 널리 쓰이는 표준 문법이 모두 지원됩니다.
3단계: 실행 버튼 누르기
실행 버튼을 누르면 오른쪽 에디터에 변환된 HTML 코드가 즉시 출력됩니다.
GitHub Flavored Markdown 사양을 지원하므로 | col1 | col2 | 형식의 파이프 표나 - [x] 형태의 작업 목록 체크박스도 올바른 HTML 태그로 변환됩니다.
모든 연산은 브라우저의 자바스크립트 엔진 안에서만 실행되므로, 공개 전의 원고나 사내 기밀 문서를 붙여넣어도 외부로 유출될 위험이 없습니다.
지원하는 마크다운 문법
실무에서 자주 쓰이는 주요 GFM 문법을 지원합니다.
- 제목 (
#부터######까지) - 단락 및 줄바꿈
- 강조 서식 (
**굵게**,_기울임_,~~취소선~~) - 순서 없는 목록 및 순서 있는 목록
- 작업 목록 (Task lists:
- [ ],- [x]) - 링크 및 이미지
- 인라인 코드 및 펜스 코드 블록 (백틱 3개 사용)
- 표(테이블)
- 인용구 (
>) - 가로 구분선 (
---)
수식 표기법(KaTeX / MathJax)은 지원하지 않습니다. 마크다운 표 문법(파이프 구분, 정렬 콜론, 셀 안 이스케이프 등)을 다룰 때 주의할 점은 헤더 행과 구분 행의 열 수가 일치해야 정상적인 HTML <table>로 변환된다는 점입니다. 자세한 작성법은 마크다운 표 작성법을 참고하세요.
라이브러리나 CLI 명령어로 변환하는 경우
단발성 작업이라면 브라우저 변환기로 충분하지만, CI/CD 빌드 파이프라인에 통합하거나 정적 사이트 생성기를 직접 구축하거나 애플리케이션 내부에서 마크다운을 렌더링해야 한다면 자바스크립트 라이브러리나 CLI 도구를 사용하는 것이 좋습니다. 널리 사용되는 선택지를 비교합니다.
marked.js (브라우저 / Node.js 모두 지원)
빠르고 가벼운 마크다운 파서로, 브라우저와 Node.js 환경 모두에서 동작합니다. npm install marked로 설치한 뒤 한 줄의 코드로 변환할 수 있습니다.
import { marked } from 'marked';
const html = marked.parse('# 제목\n\n이것은 **굵은 글씨**입니다.');
GFM이 기본적으로 활성화되어 있어 작업 목록, 파이프 표, 펜스 코드 블록이 추가 설정 없이 사양에 맞춰 변환됩니다.
별도의 빌드 환경 없이 CDN에서 불러와 웹 페이지 내부에서 직접 변환할 수도 있습니다. 다만 사용자가 입력한 텍스트처럼 신뢰할 수 없는 입력을 다룰 때는 DOMPurify 같은 새니타이저(Sanitizer)를 반드시 함께 사용해야 합니다.
<script type="module">
import { marked } from 'https://cdn.jsdelivr.net/npm/marked/lib/marked.esm.js';
document.body.innerHTML = marked.parse('# 브라우저에서 직접 변환');
</script>
markdown-it (확장성 중심)
플러그인 아키텍처를 기반으로 설계된 파서입니다. 각주, 커스텀 컨테이너 블록, 사이트 고유의 문법 확장이 필요한 프로젝트에 적합합니다.
import MarkdownIt from 'markdown-it';
const md = new MarkdownIt({ html: true, linkify: true });
const html = md.render('# 제목\n\n이것은 **굵은 글씨**입니다.');
표와 작업 목록은 기본 상태에서는 비활성화되어 있으므로, GFM 수준의 동작이 필요하다면 markdown-it-task-lists 같은 플러그인을 별도로 추가해야 합니다.
remark (unified 파이프라인)
marked나 markdown-it이 마크다운 문자열을 한 번에 HTML 문자열로 변환하는 반면, remark새 탭에서 열립니다는 마크다운을 먼저 구문 트리(AST)로 파싱한 후 플러그인을 통해 변환을 거쳐 HTML로 직렬화합니다. remark-gfm으로 표와 작업 목록을 활성화하고, remark-rehype를 통해 HTML 구문 트리로 전환한 뒤, rehype-sanitize 등의 가공을 거쳐 마지막에 rehype-stringify로 HTML을 출력합니다.
import { remark } from 'remark';
import remarkGfm from 'remark-gfm';
import remarkRehype from 'remark-rehype';
import rehypeSanitize from 'rehype-sanitize';
import rehypeStringify from 'rehype-stringify';
const html = await remark()
.use(remarkGfm)
.use(remarkRehype)
.use(rehypeSanitize)
.use(rehypeStringify)
.process('# 제목\n\n이것은 **굵은 글씨**입니다.');
한 줄로 끝나는 marked.parse()에 비해 코드가 늘어나지만, 이것이 파이프라인 구조의 장점이자 트레이드오프입니다. XSS 방지를 위한 새니타이즈, 제목 링크 앵커 추가, 목차(TOC) 자동 생성처럼 변환 과정 중간에 다양한 가공이 필요할 때 적합합니다. FormatArc 자체도 이러한 용도에 맞춰 구분하고 있습니다. Markdown to HTML 변환기는 빠른 처리를 위해 marked를 사용하고, 블로그 페이지 렌더링에는 remark + rehype 파이프라인(GFM 지원, 새니타이즈, 목차용 제목 슬러그 생성)을 사용합니다.
Pandoc (CLI)
다양한 문서 형식을 지원하는 강력한 범용 문서 변환 CLI 도구입니다. 대량의 파일 일괄 변환이나 마크다운/HTML을 넘어 PDF나 Word(DOCX) 등 다른 형식으로의 변환까지 다룰 수 있다는 점이 큰 장점입니다.
pandoc -f markdown -t html input.md -o output.html
옵션 플래그를 통해 CommonMark, GFM, MultiMarkdown 등의 파서를 전환할 수 있습니다. 단일 텍스트 변환 속도는 자바스크립트 라이브러리보다 느릴 수 있지만, 광범위한 파일 포맷 지원과 유연성은 CLI 도구 중 단연 돋보입니다.
기본 출력은 <html>이나 <head> 태그가 없는 HTML 조각(fragment)입니다. Pandoc 매뉴얼새 탭에서 열립니다에서 자주 쓰이는 주요 옵션 플래그는 다음과 같습니다.
| 플래그 | 역할 |
|---|---|
-f gfm | 입력을 Pandoc 확장 마크다운이 아닌 GitHub Flavored Markdown으로 해석 |
--standalone | 조각이 아닌 <html>과 <head>를 포함한 완전한 HTML 문서로 출력 |
--toc | 본문 제목을 기반으로 목차(Table of Contents)를 자동 생성 (--standalone과 함께 사용) |
--template FILE | 지정한 사용자 정의 HTML 템플릿 파일에 내용을 채워 출력 |
--embed-resources | 이미지, CSS, 스크립트를 파일 내에 인라인으로 포함하여 단일 독립 파일 생성 |
--highlight-style STYLE | 코드 블록의 구문 강조(Syntax Highlighting) 테마 선택 (pygments, kate 등) |
용도별 비교
| 도구 | 브라우저 실행 | GFM 표 기본 지원 | 설치 필요 | 적합한 용도 |
|---|---|---|---|---|
| FormatArc (이 도구) | 지원 | 지원 | 불필요 | 복사·붙여넣기를 통한 단발성 변환 |
| marked.js | 지원 | 지원 | 필요 (npm) | 웹 애플리케이션 및 프론트엔드 내장 |
| markdown-it | 지원 | 플러그인 필요 | 필요 (npm) | 독자적인 문법 확장이나 플러그인이 필요한 경우 |
| remark | 지원 | 플러그인 필요 (remark-gfm) | 필요 (npm) | 새니타이즈, 목차 생성 등 다단계 파이프라인 |
| Showdown | 지원 | 옵션 지정 (tables: true) | 필요 (npm) | 기존 프로젝트 유지보수 및 HTML to Markdown 역변환 |
| Pandoc | 미지원 | 지원 | 필요 (바이너리 설치) | 빌드 파이프라인, 대량 배치 처리, 다중 포맷 변환 |
단순히 텍스트를 붙여넣어 HTML 결과물만 얻고 싶다면 브라우저 기반 도구가 가장 빠릅니다. 빌드 자동화에는 Pandoc, 애플리케이션 번들에 파서를 포함해야 한다면 marked.js나 markdown-it을 추천합니다.
변환된 HTML을 사용할 때의 주의점
신뢰할 수 없는 입력에 대한 새니타이즈(Sanitize) 필수
마크다운 사양은 원본 HTML 태그의 직접 삽입을 허용합니다. 따라서 입력 마크다운에 <script> 태그나 위험한 속성이 포함되어 있으면 변환된 HTML에도 그대로 남게 됩니다. 본인이 직접 작성한 원고라면 문제없지만, 웹 폼 입력이나 외부 사용자의 콘텐츠를 처리할 때는 화면에 렌더링하기 전에 반드시 DOMPurify 같은 라이브러리로 새니타이즈 처리를 거쳐야 합니다.
CSS 스타일은 포함되지 않음
출력되는 HTML은 어디까지나 문서의 의미와 구조만 담고 있으며 CSS 스타일은 포함하지 않습니다. 변환된 HTML을 블로그나 웹사이트에 붙여넣었을 때 해당 플랫폼의 기본 스타일시트나 테마에 맞춰 시각적 디자인이 적용됩니다.
코드 블록의 구문 강조(Syntax Highlighting)
마크다운에서 ```javascript처럼 언어를 지정하더라도 변환 결과에는 <code class="language-javascript"> 형태로 클래스만 부여됩니다. 실제 색상이 적용된 구문 강조를 구현하려면 Prism.js나 highlight.js 같은 하이라이트 라이브러리를 페이지에 별도로 로드해야 합니다.
자주 묻는 질문
GitHub Flavored Markdown(표·작업 목록·코드 블록)을 지원하나요?
네, 지원합니다. GitHub Flavored Markdown 사양에 따라 변환하므로 | col1 | col2 | 형식의 파이프 표, - [x] 형식의 작업 목록 체크박스, ~~취소선~~, 언어 힌트가 포함된 펜스 코드 블록 등이 모두 표준 HTML 요소로 올바르게 변환됩니다.
변환 처리는 브라우저 안에서만 이루어지나요?
네. 마크다운 파싱과 HTML 코드 생성은 사용자의 브라우저 내부 자바스크립트로 처리됩니다. 서버로 텍스트가 전송되지 않으므로 사내 비공개 문서나 개인적인 메모도 안전하게 변환할 수 있습니다.
변환된 HTML을 웹에 바로 공개해도 안전한가요?
직접 작성한 글이라면 그대로 공개해도 무방합니다. 다만 마크다운은 원본 HTML 태그 삽입을 허용하므로, 출처를 신뢰할 수 없는 사용자 입력 텍스트를 변환할 경우 <script> 태그가 실행될 위험이 있습니다. 이런 경우에는 렌더링 전에 DOMPurify 등의 새니타이저를 거쳐야 안전합니다.
Pandoc과 비교했을 때 어떤 점이 다른가요?
Pandoc은 다양한 파일 형식을 지원하고 출력 옵션을 세밀하게 지정할 수 있는 강력한 CLI 도구이지만, 설치 과정과 터미널 조작이 필요합니다. FormatArc 변환기는 브라우저에서 붙여넣고 버튼만 누르면 바로 결과를 얻을 수 있어 단발성 변환에 적합합니다. 빌드 자동화나 대량 일괄 변환에는 Pandoc이 적합합니다.
HTML을 다시 마크다운으로 되돌리는 역변환도 가능한가요?
네, 가능합니다. 반대 방향 변환은 HTML to Markdown 변환기를 사용하면 됩니다. HTML 태그를 깔끔하게 제거하고 구조화된 마크다운 텍스트로 변환해 줍니다. 자세한 사용법은 HTML to Markdown 변환 가이드를 참고하세요.
정리
- 마크다운을 HTML로 변환하는 작업은 블로그 게시, HTML 이메일 작성, CMS 입력 등 다양한 개발 및 문서화 작업에서 필요합니다.
- 즉시 단발성 변환이 필요할 때는 브라우저에서 안전하게 실행되는 Markdown to HTML 도구를 활용하면 빠릅니다.
- 애플리케이션 개발에는 marked.js나 markdown-it, 복합 파이프라인에는 remark, 대량 일괄 처리에는 Pandoc이 적합합니다.
- 외부 사용자 입력을 HTML로 변환할 때는 XSS 방지를 위해 반드시 DOMPurify 등으로 새니타이즈를 수행해야 합니다.
- HTML 코드를 다시 마크다운으로 변환하고 싶다면 HTML to Markdown 도구를 활용해 보세요.
- CSV 데이터를 마크다운 표로 변환하고 싶다면 CSV to Markdown 변환 가이드를, 브라우저 툴바에서 바로 변환하고 싶다면 FormatArc 크롬 확장프로그램 사용법을 참고하세요.