결론부터
HTML to Markdown에 HTML 코드를 붙여넣고 실행(Run) 버튼을 누르기만 하면 즉시 깔끔한 마크다운(Markdown)이 생성됩니다. 별도의 프로그램 설치가 필요 없으며, 모든 변환 작업이 브라우저 내부에서 완결되므로 데이터가 외부 서버로 전송되지 않습니다.
출력되는 마크다운은 CommonMark새 탭에서 열립니다를 기본 문법으로 따르며, 표(테이블)·작업 목록(체크리스트)·취소선·자동 링크 등의 확장 기능은 GitHub Flavored Markdown(GFM) 사양새 탭에서 열립니다을 준수합니다.
어떤 상황에서 HTML 변환이 필요할까?
HTML로 작성된 웹 콘텐츠를 마크다운으로 변환해야 하는 상황은 실무에서 자주 발생합니다.
워드프레스(WordPress)나 CMS에서의 마이그레이션
워드프레스나 기존 CMS의 글 데이터는 대부분 HTML 형식으로 내보내집니다. 이를 Hugo, Astro, Jekyll 같은 정적 사이트 생성기나 velog, Tistory, GitHub Pages 같은 마크다운 기반 플랫폼으로 이전하려면 각 글을 마크다운으로 변환해야 합니다. 글 수가 적다면 수작업으로 복사할 수도 있지만, 서식과 구조를 깨뜨리지 않고 일괄 변환하려면 변환 도구를 쓰는 것이 안전합니다.
Notion 내보내기(Export) 데이터 정리
Notion은 HTML 형식으로 내보내기 기능을 제공합니다. 하지만 Notion이 생성하는 HTML에는 고유한 class 속성이나 여러 겹으로 중첩된 div 태그가 대량으로 포함되어 있어 다른 에디터나 도구에서 재활용하기 번거롭습니다. 이를 마크다운으로 변환하면 불필요한 레이아웃 태그가 제거되고 순수한 텍스트 구조만 남아 가독성이 높아집니다.
웹 페이지 스크랩 및 메모 클립
웹 페이지의 일부 내용을 메모 앱(Obsidian, Logseq 등)이나 기술 문서에 인용할 때, HTML을 그대로 복사하면 불필요한 태그와 인라인 스타일까지 함께 복사됩니다. 마크다운으로 변환하면 제목, 목록, 링크, 코드 블록 같은 구조만 깔끔하게 보존할 수 있습니다. 또한 LLM(대형 언어 모델)에 프롬프트 컨텍스트로 전달할 때도 복잡한 HTML보다 마크다운이 토큰을 훨씬 적게 소모하므로 유리합니다.
HTML 이메일 본문 재활용
업무상 수신한 HTML 이메일 본문을 사내 위키나 기술 문서로 옮길 때 수동으로 태그를 지우는 것은 많은 시간이 듭니다. 변환 도구를 사용하면 본문의 제목·목록·링크 구조를 유지하면서 깔끔한 마크다운 텍스트로 추출할 수 있습니다.
FormatArc에서 변환하는 방법
HTML to Markdown 변환기는 HTML을 붙여넣고 버튼을 누르면 즉시 마크다운으로 바꿔 줍니다.
단계 1: 도구 열기
HTML to Markdown 페이지에 접속합니다.
단계 2: HTML 붙여넣기
왼쪽 입력 에디터에 변환하려는 HTML 코드를 붙여넣습니다. <table>, <ul>, <ol>, <a>, <img>, <pre>, <code> 등 주요 HTML 태그를 모두 지원합니다.
단계 3: 실행 버튼 누르기
실행 버튼을 누르면 오른쪽 에디터에 마크다운이 즉시 출력됩니다.
모든 처리는 브라우저 안에서 로컬로 완결됩니다. 사내 기밀 문서나 미공개 초안을 붙여넣어도 외부 서버로 전송되지 않으므로 안심하고 사용할 수 있습니다.
HTML 요소와 마크다운(GFM) 대응 표
대부분의 주요 HTML 요소는 마크다운으로 변환할 수 있습니다. 하지만 마크다운은 HTML보다 표현 범위가 좁고 단순한 언어이므로, 마크다운에 대응하는 문법이 없는 속성이나 시각적 스타일 태그는 변환 과정에서 제거됩니다.
아래 표는 WHATWG HTML Living Standard새 탭에서 열립니다의 주요 요소가 CommonMark새 탭에서 열립니다 및 GitHub Flavored Markdown(GFM)새 탭에서 열립니다 문법으로 어떻게 매핑되는지, 그리고 어떤 정보가 삭제되는지 정리한 것입니다.
| HTML 요소 | GFM 마크다운 대응 문법 | 변환 시 주의점 및 삭제되는 정보 |
|---|---|---|
제목 <h1>–<h6> | # ~ ###### (ATX) | 제목 레벨에 맞춰 # 개수가 지정됩니다. <h1>은 #, <h6>은 ######에 대응합니다. CommonMark 사양은 HTML과 동일하게 6단계 레벨만 정의합니다. |
순서 없는 목록 <ul> | -, *, + 마커 | 항목의 중첩 구조는 들여쓰기(indent)로 유지됩니다. 불릿 기호의 종류는 변환 도구의 기본 설정에 따릅니다. |
순서 있는 목록 <ol> | 1., 2., … 마커 | 시작 번호를 지정하는 start 속성이나 번호 유형 type(a, i 등)은 마크다운에 대응 문법이 없어 삭제됩니다. |
표(테이블) <table> | GFM 파이프 표 (` | col |
링크 <a href> | [텍스트](url) | href 주소와 링크 텍스트는 유지됩니다. target, rel 등의 속성은 삭제되며, title 속성은 선택적 형태([텍스트](url "title"))로 유지될 수 있습니다. |
이미지 <img src alt> |  | src 경로와 alt 대체 텍스트는 유지됩니다. width, height, srcset, loading 같은 속성은 마크다운에 대응 문법이 없어 삭제됩니다. |
코드 <pre> / <code> | 코드 블록(```) / 인라인 `code` | <pre><code>는 펜스 코드 블록으로 변환되고, 단독 <code>는 인라인 코드가 됩니다. class="language-..." 힌트는 코드 블록 언어 지정자로 출력될 수 있습니다. |
인용구 <blockquote> | > 접두사 | 각 줄 앞에 > 기호가 붙습니다. 중첩된 인용문은 >>처럼 누적됩니다. cite 속성은 마크다운에 대응 문법이 없어 삭제됩니다. |
굵게 <strong> / <b> | **텍스트** | 의미적 강조(<strong>)와 시각적 굵기(<b>)는 동일하게 ** 문법으로 합쳐지며, 의미적 구분은 유지되지 않습니다. |
기울임 <em> / <i> | *텍스트* | 강조(<em>)와 이탤릭(<i>)은 동일하게 * 문법으로 합쳐지며, 의미적 구분은 유지되지 않습니다. |
위 표에 없는 요소들(style, class, 레이아웃용 <div>/<span> 래퍼 태그, 인라인 이벤트 핸들러 등)은 자동으로 제거되어 깔끔한 구조적 마크다운만 남습니다. 단, GFM은 인라인 HTML을 허용하므로 일부 변환 도구는 지원되지 않는 태그를 삭제하는 대신 원본 HTML 조각 그대로 마크다운 내에 남겨 두기도 합니다.
CLI 및 프로그래밍 라이브러리 선택지
브라우저 도구 외에도 터미널 환경(CLI)이나 프로그램 코드 내에서 HTML을 마크다운으로 변환해야 할 때가 있습니다. 사용하는 기술 스택에 맞는 도구를 선택하면 됩니다.
Pandoc (범용 문서 변환 CLI)
pandoc -f html -t markdown -o output.md input.html
Pandoc은 HTML뿐만 아니라 Word(docx), EPUB, LaTeX 등 다양한 문서 형식을 상호 변환할 수 있는 강력한 CLI 도구입니다. GFM 표 문법을 사용하려면 -t gfm 옵션을 지정합니다. 대량의 파일 일괄 변환이나 복잡한 문서 구조를 다룰 때 적합하며, 로컬 환경에 설치해야 합니다.
Turndown (JavaScript / Node.js)
import TurndownService from "turndown";
const turndown = new TurndownService();
const markdown = turndown.convert("<h1>Hello</h1><p>World</p>");
console.log(markdown);
Node.js 생태계에서 가장 널리 쓰이는 표준 라이브러리입니다. turndown-plugin-gfm 플러그인을 추가하면 GFM 표, 취소선, 체크리스트까지 지원합니다. 브라우저 환경에서도 동작하므로 자체 웹 애플리케이션에 변환 기능을 내장할 때도 유용합니다.
Python 및 Go 라이브러리
빌드 파이프라인이나 데이터 수집 파이프라인이 Node.js가 아닌 Python이나 Go로 구성되어 있다면 각 생태계의 대표 라이브러리를 사용할 수 있습니다.
markdownify (Python)
pip install markdownify
from markdownify import markdownify
html = "<h1>Title</h1><p>Hello <strong>world</strong></p>"
print(markdownify(html, heading_style="ATX"))
markdownify는 BeautifulSoup을 기반으로 작동하므로 웹 크롤링이나 스크랩으로 수집한 다소 불완전한 HTML도 안정적으로 처리합니다. heading_style="ATX", bullets="-*+", strip=["script", "style"] 같은 옵션으로 출력 형태를 세밀하게 제어할 수 있습니다.
html2text (Python)
pip install html2text
import html2text
h = html2text.HTML2Text()
print(h.handle("<h1>Title</h1><p>Hello world</p>"))
오랫동안 널리 유지보수되어 온 라이브러리로, Python 코드 내부뿐만 아니라 CLI 도구(html2text input.html)로도 작동합니다. 저장된 웹 페이지를 단발성으로 빠르게 변환할 때 편리합니다.
html-to-markdown (Go - JohannesKaufmann)
go install github.com/JohannesKaufmann/html-to-markdown/cli/html2markdown@latest
html2markdown < input.html > output.md
Go 커뮤니티의 사실상 표준 라이브러리입니다. 라이브러리와 독립 CLI 바이너리 형태로 모두 제공되며, 표 지원 및 커스텀 변환 룰 확장이 가능합니다. CI 러너나 Docker 컨테이너 환경에서 단일 정적 바이너리로 가볍게 실행하기에 적합합니다.
용도별 도구 선택 가이드
| 도구 | 설치 필요 여부 | 기반 언어 | 추천 사용처 |
|---|---|---|---|
| FormatArc | 불필요 (웹 브라우저) | — | 즉각적인 단발성 변환, 보안이 중요한 사내 데이터 |
| Pandoc | 필요 (Homebrew / apt 등) | CLI | 대량 일괄 변환, 다양한 문서 포맷 처리 |
| Turndown | npm 설치 | JavaScript | Node.js 서비스, 웹 프론트엔드 내장 |
| markdownify | pip 설치 | Python | 웹 크롤링 및 데이터 수집 파이프라인 |
| html2text | pip 설치 | Python | 저장된 웹 페이지 텍스트 추출 및 CLI 작업 |
| JohannesKaufmann | go install | Go | CI/CD 파이프라인, Docker용 경량 정적 바이너리 |
HTML 표(테이블)를 마크다운으로 변환할 때의 주의점
HTML을 마크다운으로 변환할 때 가장 자주 오류가 발생하거나 서식이 깨지는 부분이 바로 <table> 태그입니다.
마크다운의 파이프 표 문법은 GitHub Flavored Markdown 사양새 탭에서 열립니다에서 정의되어 있으며, 헤더 행, 데이터 행, 열 정렬(align)까지는 깔끔하게 표현할 수 있습니다. 하지만 HTML 테이블이 제공하는 복잡한 레이아웃 기능을 모두 지원하지는 않습니다.
깔끔하게 변환되는 표준 테이블 구조
<thead>와 <tbody>로 구조화되어 있고, 셀이 단순한 <td>와 <th>로 이루어져 있으며, 헤더에 align="left|center|right" 정렬 속성을 사용하는 일반적인 표는 손실 없이 파이프 표로 변환됩니다.
<table>
<thead><tr><th>상품명</th><th align="right">가격</th></tr></thead>
<tbody>
<tr><td>사과</td><td align="right">1,200</td></tr>
<tr><td>바나나</td><td align="right">800</td></tr>
</tbody>
</table>
위 HTML은 다음과 같이 깔끔한 마크다운 파이프 표로 변환됩니다.
| 상품명 | 가격 |
|--------|------:|
| 사과 | 1,200 |
| 바나나 | 800 |
마크다운으로 직접 변환되지 않는 3가지 구조
마크다운 표 사양에 직접 대응하는 문법이 없어 변환 시 손실이 일어나는 대표적인 구조는 다음과 같습니다.
colspan/rowspan(셀 병합) — 마크다운 파이프 표는 모든 행과 열이 직사각형 격자 형태여야 합니다. 셀 병합 정보는 지원되지 않으며, 변환 도구에 따라 셀이 분할되거나 병합 내용이 한 셀로 합쳐집니다.- 셀 내부의 블록 요소 —
<td>셀 안에 목록(<ul>/<ol>), 코드 블록(<pre>), 또 다른 중첩 테이블(<table>) 같은 블록 레벨 요소가 들어가면 파이프 표 구조가 깨집니다. 인라인 요소(<strong>,<em>,<a>,<code>)는 정상적으로 변환됩니다. - 셀 내부 줄바꿈 (
<br>) — 셀 안에서 줄바꿈이 일어나는 경우 파서에 따라 줄바꿈이 무시되거나 GFM이 허용하는 인라인 HTML 태그인<br>형태로 그대로 삽입됩니다.
실무적인 대처 방법
파이프 표 문법으로 표현하기 어려운 복잡한 표를 다룰 때는 다음 두 가지 방법으로 대처할 수 있습니다.
- 전체 본문은 마크다운으로 변환하되, 해당 복잡한 테이블만 raw HTML(
<table>...</table>) 형태로 그대로 유지합니다. GFM 및 대부분의 정적 사이트 생성기(GitHub, velog, Tistory, Hugo 등)는 마크다운 내 인라인 HTML 태그를 정상적으로 렌더링합니다. - 복잡한 레이아웃이 아니라 순수한 데이터셋이라면, 데이터를 행과 열로 정리한 뒤 CSV to Markdown 변환기를 통해 마크다운 표를 생성하는 편이 안정적입니다.
마크다운 표 문법(파이프 구분, 열 정렬, 셀 내 이스케이프, 줄바꿈)에 대한 자세한 내용은 마크다운 표 만들기와 GFM 표 문법 치트시트를 참고하세요. 테이블 변환에 특화된 줄바꿈 처리 및 정렬 유지 방법은 HTML 테이블을 마크다운 표로 변환에서도 확인할 수 있습니다.
자주 발생하는 문제와 해결 방법
스타일 및 class 속성 제거
HTML 태그에 지정된 style 인라인 CSS나 class 속성은 마크다운에 대응하는 개념이 없으므로 변환 시 자동으로 삭제됩니다. 원래 디자인 정보가 필요한 프로젝트라면 변환 전 원본 HTML을 보관해 두어야 합니다.
복사 원본이 Word, Google Docs, 또는 웹 페이지인 경우 불필요한 태그(<o:p>, mso-* 스타일, 의미 없는 span 태그 등)가 섞여 들어오기 쉽습니다. 이러한 서식 정리 및 span 태그 제거에 특화된 방법은 HTML 붙여넣기로 마크다운 변환을 참고하세요. 이런 경우 마크다운으로 구조만 깨끗하게 변환한 후, 스타일링이 다시 필요하다면 Markdown to HTML 변환기를 거쳐 원하는 CSS 클래스를 적용해 재렌더링하는 방식이 유용합니다.
이미지 상대 경로 문제
<img src="..."> 태그는  마크다운 문법으로 변환됩니다. 하지만 원본 HTML에서 상대 경로(예: ./images/photo.png)로 작성된 이미지는 마크다운 파일을 다른 플랫폼이나 프로젝트로 이동했을 때 경로가 일치하지 않아 이미지가 깨질 수 있습니다.
HTML to Markdown으로 먼저 변환하여 이미지 대체 텍스트(alt)와 링크 구조를 확인한 후, 이미지 파일 복사 및 경로 수정을 별도 단계로 진행하는 것이 안전합니다.
공백, , 이스케이프 역슬래시(\) 생성
변환된 마크다운 결과물에 예기치 않은 문자가 포함될 수 있습니다. 엔티티는 변환기에 따라 일반 공백이나 줄바꿈 없는 공백으로 처리되며, 연속된 공백은 하나의 공백으로 축약됩니다.
또한 본문 중 *, _, #, [ 같은 문자 앞에 역슬래시(\)가 자동으로 붙는 경우가 있습니다. 이는 해당 기호가 마크다운 서식 문법(강조, 제목, 링크 등)으로 잘못 해석되지 않도록 변환 엔진이 안전하게 이스케이프하는 동작입니다. 불필요하다고 판단되는 경우 해당 문자가 목록이나 강조의 시작점이 아닌지 확인한 후 제거하면 됩니다.
자주 묻는 질문
GitHub Flavored Markdown(GFM)의 표를 지원하나요?
네, 지원합니다. HTML의 <table> 요소는 GFM 파이프 표(| 열1 | 열2 |) 형태로 변환되며, <thead> 헤더 행과 기본적인 열 정렬(align) 속성도 반영됩니다.
변환 작업은 브라우저 내부에서 처리되나요?
네, HTML 파싱과 마크다운 텍스트 생성은 모두 사용자의 웹 브라우저 내부에서 JavaScript로 실행됩니다. 사내 내부 문서나 미공개 원고를 입력해도 외부 서버로 전송되지 않습니다.
Pandoc이나 Turndown과 어떤 점이 다른가요?
Pandoc은 로컬 CLI 환경 설치가 필요하고, Turndown은 Node.js 프로젝트 설정이 필요합니다. FormatArc 웹 변환기는 설치 없이 브라우저에서 즉시 붙여넣고 변환 결과를 복사할 수 있어 단발성 작업에 가장 빠릅니다. 반면 대량 자동화나 빌드 스크립트에는 Pandoc이나 Turndown 라이브러리가 더 적합합니다.
이미지와 상대 경로는 유지되나요?
<img src="..."> 태그는 로 변환되어 이미지 주소와 대체 텍스트가 보존됩니다. 원본 HTML의 상대 경로는 그대로 유지되므로, 다른 플랫폼으로 콘텐츠를 이전하는 경우 이미지 파일을 함께 복사하고 필요에 따라 경로를 수정해야 합니다.
class나 style 속성은 왜 삭제되나요?
마크다운은 스타일링이 아닌 텍스트 구조 표현을 위한 경량 마크업 언어로, 인라인 CSS나 class 속성에 해당하는 문법이 없습니다. 따라서 모든 환경에서 호환되는 깔끔하고 이식성 높은 텍스트를 만들기 위해 스타일 속성을 제거합니다.
정리
HTML을 마크다운으로 변환하는 작업은 블로그 플랫폼 이전, 웹 스크랩, Notion 데이터 정리 등 다양한 작업에서 필수적입니다.
간단한 단발성 변환이나 안전한 로컬 처리가 필요하다면 브라우저에서 바로 사용할 수 있는 HTML to Markdown 변환기를 활용해 보세요. 반대로 마크다운 문서를 HTML로 변환하는 방법은 Markdown to HTML 변환 가이드를, CSV 데이터를 마크다운 표로 만들고 싶다면 CSV to Markdown 변환 가이드를 참고하세요.