HTML to 마크다운 변환 방법 총정리 - 온라인 도구부터 Pandoc, Turndown까지

블로그 글을 노션이나 깃허브로 옮기려고 복사했는데, 태그가 잔뜩 섞인 HTML 덩어리가 붙여넣어져서 당황한 경험이 있을 겁니다. 링크는 사라지고 표는 줄줄이 풀려버리고, 결국 처음부터 다시 타이핑하는 경우도 적지 않습니다. 이럴 때 필요한 것이 HTML to 마크다운 변환입니다. 몇 초면 끝나는 작업인데 어떤 도구를 쓰느냐에 따라 결과물 품질이 크게 달라집니다.

HTML을 마크다운으로 바꿔야 하는 이유

마크다운은 2004년 존 그루버가 만든 경량 마크업 언어입니다. 현재 깃허브, 노션, 옵시디언, 디스코드, 레딧 등 대부분의 개발자 도구와 노트 앱이 기본 포맷으로 채택하고 있습니다. HTML 문서를 마크다운으로 변환하면 얻는 이점은 명확합니다.

• 가독성: 태그 없이 원문만 남아 읽고 수정하기 쉽습니다
• 버전 관리: Git에서 diff가 깔끔하게 보입니다. HTML은 한 줄 바꿔도 태그 때문에 변경 범위가 커집니다
• 이식성: 노션, 옵시디언, 깃허브 위키 등 어디에나 붙여넣을 수 있습니다
• 용량: 같은 내용이라면 마크다운 파일이 HTML보다 보통 30~60% 가볍습니다

특히 기술 블로그를 워드프레스에서 정적 사이트(Hugo, Jekyll, Astro)로 이전할 때는 수백 개 글을 한꺼번에 변환해야 하므로 도구 선택이 중요해집니다.

설치 없이 쓰는 온라인 변환 도구

글 몇 개만 옮기는 정도라면 브라우저에서 바로 쓰는 도구가 가장 빠릅니다. 왼쪽에 HTML을 붙여넣으면 오른쪽에 마크다운이 실시간으로 나오는 구조가 대부분입니다.

대표적인 온라인 변환기

온라인 도구를 고를 때 확인해야 할 기준은 세 가지입니다. 표를 마크다운 테이블로 바꿔주는지, 중첩 리스트를 들여쓰기로 유지하는지, 코드 블록의 언어 표기를 살려주는지입니다. 이 세 가지가 깨지면 변환 후 손으로 고치는 시간이 변환으로 아낀 시간보다 길어집니다.

Pandoc과 Turndown으로 대량 변환하기

파일이 10개를 넘어가면 온라인 도구에 하나씩 붙여넣는 방식은 비효율적입니다. 이 단계부터는 명령줄 도구가 답입니다.

Pandoc: 문서 변환의 표준

Pandoc은 HTML, 워드, LaTeX, EPUB 등 40개 이상의 포맷을 서로 변환하는 도구입니다. 설치 후 명령 한 줄이면 끝납니다.

pandoc input.html -f html -t gfm -o output.md

여기서 gfm은 GitHub Flavored Markdown을 뜻합니다. 기본값인 markdown 대신 gfm을 지정해야 표와 취소선이 깃허브 방식으로 출력됩니다. 폴더 전체를 한 번에 처리하려면 셸 반복문과 조합하면 됩니다.

for f in *.html; do pandoc "$f" -f html -t gfm -o "${f%.html}.md"; done

Pandoc의 강점은 정확성입니다. 각주, 정의 목록, 중첩 인용까지 규칙대로 변환합니다. 단점은 인라인 스타일이 많은 워드프레스 출력물에서 불필요한 <div>가 그대로 남는 경우가 있다는 점입니다. 이때는 --wrap=none 옵션으로 줄바꿈을 끄고 -t gfm-raw_html로 원시 HTML 출력을 제거하면 훨씬 깔끔해집니다.

Turndown: 자바스크립트 프로젝트라면

Turndown은 Node.js와 브라우저에서 모두 동작하는 자바스크립트 라이브러리입니다. 크롤러나 CMS 마이그레이션 스크립트에 바로 끼워 넣을 수 있어 개발자들이 가장 많이 씁니다.

const TurndownService = require('turndown');
const td = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
const markdown = td.turndown(htmlString);

headingStyle: 'atx'는 제목을 # 기호로, codeBlockStyle: 'fenced'는 코드 블록을 백틱 세 개로 출력하라는 뜻입니다. 기본값은 밑줄 방식 제목과 4칸 들여쓰기 코드라서 이 두 옵션은 거의 필수로 지정합니다. 표 변환은 기본 포함이 아니므로 turndown-plugin-gfm 플러그인을 추가해야 합니다.

파이썬 환경이라면 markdownify

파이썬 사용자는 pip install markdownify 한 줄로 설치되는 markdownify가 편합니다. BeautifulSoup 기반이라 크롤링 코드와 자연스럽게 이어집니다. 스크래핑한 페이지를 바로 마크다운으로 저장하는 파이프라인에 적합합니다.

변환 시 깨지기 쉬운 요소와 대처법

어떤 도구를 쓰든 100% 완벽한 변환은 없습니다. 자주 문제가 되는 요소를 미리 알고 있으면 후처리 시간을 크게 줄일 수 있습니다.

• 셀 병합된 표: 마크다운 테이블은 rowspan, colspan을 표현할 수 없습니다. 병합 셀이 있는 표는 HTML 그대로 두거나 구조를 단순화해야 합니다
• 이미지 경로: 상대 경로 이미지는 변환 후 링크가 끊깁니다. 변환 전 절대 URL로 바꾸거나 이미지를 함께 옮겨야 합니다
• 인라인 스타일: 글자 색, 폰트 크기 같은 CSS 스타일은 마크다운에 대응 문법이 없어 전부 사라집니다
• 중첩 리스트: 3단계 이상 중첩되면 들여쓰기가 어긋나는 도구가 많습니다. 변환 후 눈으로 확인이 필요합니다
• 특수문자 이스케이프: 본문에 *, _, #이 있으면 백슬래시가 붙어 \*처럼 나옵니다. 의도한 동작이지만 지저분해 보일 수 있습니다

이런 문제는 결국 HTML이 표현할 수 있는 범위가 마크다운보다 넓기 때문에 생깁니다. 변환은 정보를 덜어내는 과정이라는 점을 받아들이고, 덜어내도 되는 것과 안 되는 것을 먼저 구분하는 편이 빠릅니다.

변환 도구의 성능보다 중요한 것은 원본 HTML의 상태입니다. 의미 구조를 갖춘 깔끔한 HTML은 어떤 도구로 변환해도 결과가 좋고, 워드에서 내보낸 스타일 범벅 HTML은 최고의 도구로도 한계가 있습니다. 변환 전 불필요한 태그를 정리하는 5분이 변환 후 수정하는 30분을 아껴줍니다.

상황별 추천 워크플로우

상황에 따라 도구를 다르게 쓰는 것이 핵심입니다. 정리하면 다음과 같습니다.

글 1~5개를 옮길 때

온라인 변환기로 충분합니다. 변환 후 표와 코드 블록만 확인하면 됩니다. 5분 안에 끝납니다.

블로그 전체를 이전할 때

Pandoc을 반복문으로 돌리고, 이미지 경로는 별도 스크립트로 일괄 치환합니다. 변환 후 무작위로 10% 정도 샘플을 열어 검수하는 방식이 효율적입니다. 수백 개 문서를 처리하면서 각 단계에 걸리는 시간을 재두면 이후 프로젝트 일정 산정에 도움이 되는데, 이럴 때는 별도 프로그램 없이 온라인 스톱워치로 구간별 소요 시간을 기록해두는 정도면 충분합니다.

서비스에 변환 기능을 넣을 때

Node.js라면 Turndown, 파이썬이라면 markdownify를 코드에 직접 통합합니다. 사용자 입력 HTML은 반드시 sanitize 과정을 거친 뒤 변환해야 스크립트 삽입 문제를 피할 수 있습니다.

변환 후 검수 체크리스트

지금 당장 해볼 일은 두 가지입니다. 옮기려는 HTML 하나를 Turndown 데모나 Pandoc 웹에 붙여넣어 표와 코드 블록이 어떻게 나오는지 먼저 확인하고, 결과가 만족스럽지 않다면 원본에서 인라인 스타일을 걷어낸 뒤 다시 시도해 보세요. 이 두 단계만 거쳐도 HTML to 마크다운 변환에서 겪는 문제의 대부분이 해결됩니다.