HTML to Markdown 변환기

HTML to Markdown 변환이란 무엇인가요?

HTML to Markdown 변환은 HTML 마크업을 John Gruber가 2004년에 만든 경량 일반 텍스트 서식 문법인 Markdown으로 변환하는 과정입니다. Markdown은 렌더링 없이도 읽기 쉽게 설계되었습니다. HTML이 <strong>이나 <a href="">처럼 여는 태그와 닫는 태그를 필요로 하는 반면, Markdown은 약식 문자를 사용합니다: **굵게**, [링크](url), # 제목. HTML을 Markdown으로 변환하면 원시 HTML보다 읽기, 편집, 버전 관리가 쉬운 파일이 생성됩니다.

변환 과정은 HTML 요소를 Markdown의 동등한 표현으로 매핑합니다. <h2>는 ##이 되고, <ul><li>는 - 항목이 되며, <a> 태그는 [텍스트](url)가 됩니다. <div>, <span>, 사용자 정의 데이터 속성처럼 Markdown에 직접 대응하는 표현이 없는 HTML 요소도 있습니다. 변환기는 설정에 따라 이러한 태그를 제거하거나 원시 HTML 그대로 전달합니다.

Markdown은 개발자 문서(GitHub, GitLab, Bitbucket), 정적 사이트 생성기(Hugo, Jekyll, Astro), 노트 앱(Obsidian, Notion), 기술 블로그의 표준 작성 형식이 되었습니다. 기존 HTML 콘텐츠를 Markdown으로 변환하는 것은 웹사이트를 마이그레이션하거나, CMS 콘텐츠를 가져오거나, 웹 페이지를 이식 가능한 형식으로 보관할 때 흔히 수행하는 작업입니다. HTML과 달리 Markdown 파일은 버전 관리에서 깔끔한 diff를 생성하므로 문서 변경에 대한 코드 리뷰가 실용적입니다.

HTML to Markdown 변환기를 사용하는 이유

HTML을 Markdown으로 수동으로 재작성하는 것은 느리고 오류가 발생하기 쉬운 작업입니다. 특히 중첩 목록, 테이블, 또는 수십 개의 링크가 있는 페이지는 더욱 그렇습니다. 자동화된 변환기는 구조적 매핑을 즉시 그리고 일관되게 처리합니다.

HTML to Markdown 활용 사례

HTML to Markdown 요소 참조

아래 표는 일반적인 HTML 요소가 Markdown의 동등한 표현으로 어떻게 매핑되는지 보여줍니다. 이 매핑은 테이블, 취소선, 작업 목록으로 CommonMark 명세를 확장한 GitHub Flavored Markdown(GFM) 규칙을 따릅니다. 여기에 없는 요소(<div>, <form>, 사용자 정의 웹 컴포넌트 등)는 Markdown에 동등한 표현이 없으며 제거되거나 원시 HTML로 전달됩니다.

Markdown 종류: GFM vs CommonMark vs 원본

모든 Markdown이 동일한 것은 아닙니다. 플랫폼마다 Markdown을 다르게 파싱하기 때문에 출력 형식이 중요합니다. 가장 일반적인 세 가지 종류는 GitHub Flavored Markdown(GFM), CommonMark, 그리고 Gruber의 원본 Markdown입니다.

코드 예제

JavaScript(Turndown), Python(markdownify 및 html2text), Go, 그리고 커맨드라인의 Pandoc을 활용한 실제 예제입니다.

import TurndownService from 'turndown'

const turndown = new TurndownService({ headingStyle: 'atx' })
const html = '<h1>Title</h1><p>A <strong>bold</strong> paragraph.</p>'
const md = turndown.turndown(html)
console.log(md)
// → "# Title\n\nA **bold** paragraph."

from markdownify import markdownify

html = '<h2>Section</h2><ul><li>First</li><li>Second</li></ul>'
md = markdownify(html, heading_style='ATX')
print(md)
# → "## Section\n\n- First\n- Second"

import html2text

converter = html2text.HTML2Text()
converter.body_width = 0  # disable line wrapping

html = '<p>Visit <a href="https://example.com">Example</a> for details.</p>'
md = converter.handle(html)
print(md)
# → "Visit [Example](https://example.com) for details."

package main

import (
	"fmt"
	md "github.com/JohannesKaufmann/html-to-markdown"
)

func main() {
	converter := md.NewConverter("", true, nil)
	html := `<h3>Go Example</h3><p>Code: <code>fmt.Println()</code></p>`
	markdown, _ := converter.ConvertString(html)
	fmt.Println(markdown)
	// → "### Go Example\n\nCode: `fmt.Println()`"
}

# Convert an HTML file to Markdown
pandoc input.html -f html -t markdown -o output.md

# Pipe HTML from stdin
echo '<p>Hello <em>world</em></p>' | pandoc -f html -t markdown
# → Hello *world*

# Use GitHub-Flavored Markdown output
pandoc input.html -f html -t gfm -o output.md

자주 묻는 질문