HTML을 Markdown으로 변환하기: 언제 변환하고 무엇을 잃는가

웹 콘텐츠 작업을 해본 적이 있다면, HTML 더미를 앞에 두고 Markdown이었으면 좋겠다고 생각한 적이 분명 있을 것입니다. 아니면 그 반대로. 두 형식은 개발자 세계에서 불편한 관계로 공존합니다 — HTML은 웹의 언어이고, Markdown은 웹을 위해 글을 쓰는 사람들의 언어입니다.

이 가이드는 그 변환에 관한 것입니다: 언제 의미가 있는지, 무엇을 포기하는지, 그리고 효율적으로 처리하는 방법에 대해 설명합니다.

Markdown이란 무엇이고 개발자들이 왜 좋아하는가

Markdown은 2004년 John Gruber와 Aaron Swartz가 단순한 목표로 만들었습니다: 있는 그대로 자연스럽게 읽히면서도 깔끔한 HTML로 변환될 수 있는 일반 텍스트 형식을 만드는 것.

그 목표는 엄청난 성공을 거뒀습니다. 오늘날 Markdown은 GitHub README, GitLab 위키, Notion 페이지, Obsidian 볼트, 문서 사이트, 그리고 수많은 블로그 플랫폼에서 사용됩니다. 텍스트 편집기에서 **굵게**나 # 제목을 타이핑해 본 적이 있다면, Markdown을 이미 작성한 것입니다.

매력은 진짜입니다. 순수 HTML로 작성하는 것과 비교해 보세요:

<h2>시작하기</h2>
<p><code>npm install my-package</code>로 패키지를 설치하고 임포트하세요:</p>
<ul>
  <li>기본 내보내기를 임포트하기</li>
  <li><code>init()</code> 함수 호출하기</li>
</ul>

Markdown으로는:

## 시작하기

`npm install my-package`로 패키지를 설치하고 임포트하세요:

- 기본 내보내기를 임포트하기
- `init()` 함수 호출하기

같은 정보입니다. Markdown 버전은 더 빠르게 작성되고, 원시 형태로 읽기 쉬우며, 오류 발생 가능성이 낮습니다(닫는 태그를 잊어버릴 일이 없음). 문서와 산문 작성에는 일반적으로 더 나은 선택입니다.

HTML을 Markdown으로 변환하고 싶은 실제 상황

변환은 몇 가지 특정 상황에서 필요해집니다.

CMS에서 정적 사이트 생성기로 마이그레이션

이것이 가장 큰 경우입니다. WordPress, Wix, 또는 데이터베이스에 HTML로 콘텐츠를 저장하는 맞춤형 CMS가 있을 때, Markdown 파일로 기본 작동하는 Gatsby, Hugo, Jekyll, 또는 Astro로 이전하고 싶은 경우입니다.

콘텐츠는 여전히 존재합니다. 단지 잘못된 형식으로 있을 뿐입니다. 수백 개의 게시물을 손으로 다시 쓰는 대신, HTML을 내보내고 일괄적으로 Markdown으로 변환합니다.

이 워크플로우는 전용 CLI 도구들이 존재할 만큼 일반적입니다. 하지만 개별 게시물이나 소규모 마이그레이션의 경우, 온라인 도구만으로도 충분한 경우가 많습니다.

GitHub README와 문서 작성

GitHub는 Markdown을 아름답게 렌더링하지만, 소스 자료가 HTML로 존재하는 경우가 있습니다 — 웹페이지, 문서 사이트, 서식 있는 텍스트 형식의 설계 문서. HTML 혼란을 README에 복사-붙여넣기하는 대신, 먼저 깔끔한 Markdown으로 변환합니다.

GitBook, Read the Docs, Confluence, Notion 등 다른 문서 플랫폼에도 동일하게 적용됩니다. 대부분 Markdown 입력을 선호하거나 요구합니다.

웹 콘텐츠 보관 또는 재활용

웹페이지를 스크래핑하거나 다운로드하여 읽기 쉽고 편집 가능한 형식으로 보관하고 싶을 때, 클래스, ID, 스크립트, 추적 픽셀이 가득한 HTML은 읽기 매우 힘듭니다. 그 노이즈가 제거된 Markdown은 깔끔하고 이식성이 높습니다.

서식 있는 텍스트 붙여넣기 정리

이 상황은 자주 발생합니다: 웹페이지나 Google 문서에서 텍스트를 복사하여 편집기에 붙여넣으면 숨겨진 HTML이나 서식 있는 텍스트 포맷이 함께 들어와 온갖 문제를 일으킵니다. Markdown으로 변환하면 깔끔하고 예측 가능한 결과물을 얻을 수 있습니다.

변환 시 잃는 것들

변환 워크플로우를 결정하기 전에 솔직하게 인정해야 할 것이 있습니다: HTML은 Markdown이 할 수 없는 일들을 할 수 있습니다.

CSS 스타일링은 사라집니다. 폰트 크기, 색상, 사용자 지정 간격, 테두리, 배경 — 이런 것들은 살아남지 못합니다. Markdown에는 "이 텍스트는 빨간색"이나 "이 단락에 위쪽 여백 24px"를 표현하는 방법이 없습니다.

복잡한 테이블 지원은 부분적입니다. Markdown은 기본 테이블을 지원하지만(GitHub Flavored Markdown 확장을 통해), 단순한 것만 가능합니다. 여러 행 헤더, 셀 병합, colspan/rowspan은 Markdown에 없습니다.

href와 src 이외의 HTML 속성은 제거됩니다. data-* 속성, class, id, style, aria-* — Markdown의 링크와 이미지는 이것들을 담지 않습니다.

사용자 지정 컴포넌트와 임베드. iframe, 동영상 임베드, 사용자 지정 HTML 요소 — Markdown에는 해당하는 것이 없습니다. 이것들은 일반적으로 제거되거나 플레이스홀더 주석으로 변환됩니다.

반대 방향은 손실이 없습니다. Markdown에서 HTML로의 변환은 완전한 변환입니다 — 모든 Markdown 요소가 HTML로 깔끔하게 매핑됩니다. 반대 방향은 손실이 있습니다. 원본 HTML이 필요할 수도 있다면 백업을 보관하세요.

이것이 변환을 피해야 할 이유는 아닙니다 — 그냥 맥락일 뿐입니다. 기사, 문서, 블로그 게시물 같은 텍스트 중심 콘텐츠의 경우, 잃어버린 정보는 대개 무관합니다.

변환이 실제로 어떻게 작동하는가

HTML-to-Markdown 변환기는 내부적으로 HTML을 DOM 트리로 파싱한 다음 각 요소를 순회하며 Markdown 해당 요소로 변환합니다:

• h1h6 태그는 #######이 됩니다
• p 태그는 주위에 빈 줄이 있는 단락이 됩니다
• strong과 b 태그는 **굵게**가 됩니다
• em과 i 태그는 *기울임*이 됩니다
• a href 링크는 [텍스트](url)이 됩니다
• img src 태그는 ![alt](src)가 됩니다
• ul과 ol 태그는 Markdown 목록이 됩니다
• code 태그는 백틱으로 감싸진 코드가 됩니다

Markdown에 해당하는 요소가 없는 요소들은 제거되거나 원시 HTML로 전달됩니다(Markdown은 기술적으로 HTML의 상위 집합이므로 허용됨).

무료 HTML to Markdown 도구 사용하기

HTML to Markdown 변환기는 설치나 설정 없이 가장 일반적인 변환 시나리오를 처리합니다.

사용 방법:

1. HTML을 왼쪽 입력 패널에 붙여넣기
2. Markdown 출력이 오른쪽에 즉시 나타납니다
3. 이상해 보이는 부분이 없는지 변환 결과를 검토합니다
4. Markdown을 복사하여 필요한 곳에 사용합니다

제목, 단락, 링크, 이미지, 코드 블록, 목록, 기본 테이블을 처리하는 확립된 변환 로직으로 구축되어 있습니다. 대부분의 블로그 게시물과 문서에서 그냥 작동합니다.

수동 변환 대 자동화 도구

단일 페이지의 경우 수동 변환이 괜찮습니다 — 텍스트 편집기에서 몇 분 안에 할 수 있습니다. 10-20페이지 이상의 경우, 자동화가 유일한 합리적인 방법입니다.

수동 변환은 완전한 제어권을 줍니다. 판단 결정을 내릴 수 있습니다 — 이 테이블은 HTML로 유지, 이 섹션은 단순화, 이 앵커 텍스트는 다시 작성. 결과물은 정확히 원하는 것입니다. 하지만 확장성이 없습니다.

자동화 도구(온라인 변환기, CLI 도구, 라이브러리)는 대량 변환을 처리하고 빠릅니다. 출력이 일관됩니다. 하지만 특히 다음의 경우 거의 항상 정리 작업이 필요합니다:

• 변환에 포함된 탐색 요소들
• 상용구 텍스트(쿠키 공지, 뉴스레터 CTA)
• 복잡한 CSS 레이아웃에서 나온 이상한 포맷 아티팩트
• 변환되었지만 단순화가 필요한 테이블

대부분의 실제 마이그레이션에서 워크플로우는 다음과 같습니다: 먼저 자동화 변환, 그다음 잘못 보이는 부분에 대한 수동 정리.

알아두면 유용한 전용 도구와 라이브러리

빌드 스크립트, Node.js 앱, Python 스크립트 등에서 프로그래밍 방식으로 변환하는 경우, 개발자들이 가장 많이 사용하는 도구들입니다:

Turndown.js (JavaScript)는 Node.js 생태계에서 가장 많이 사용되는 HTML-to-Markdown 라이브러리입니다. 활발히 유지 관리되고, 설정 가능하며, 일반적인 요소들을 잘 처리합니다.

const TurndownService = require('turndown');
const turndownService = new TurndownService();
const markdown = turndownService.turndown('<h1>Hello World</h1>');

Pandoc은 문서 변환의 스위스 아미 나이프입니다. HTML, Markdown, Word, PDF, LaTeX 등 수십 가지 형식 간에 변환합니다. 복잡한 문서를 처리하는 CLI 도구가 필요하다면 pandoc이 정답입니다.

html2text (Python)는 스크래핑 및 콘텐츠 추출 파이프라인에 적합한 경량 Python 라이브러리입니다.

일회성 변환의 경우, HTML to Markdown 변환기와 같은 온라인 도구가 무엇을 설치하는 것보다 빠릅니다.

깔끔한 변환을 위한 모범 사례

변환 품질을 지속적으로 향상시키는 몇 가지 방법:

변환 전에 HTML을 정리하세요. 가능하면 HTML을 변환기에 제공하기 전에 탐색, 푸터, 사이드바 및 기타 상용구를 제거하세요.

제목 구조를 검토하세요. 원본 HTML에 일관성 없는 제목 수준이 있었다면(h1에서 h4로 바로 넘어가는 등), 변환된 Markdown도 같은 문제를 가질 것입니다.

링크를 주의 깊게 처리하세요. 원본 사이트에서 의미가 있던 상대 링크(/about)는 URL 구조가 보존되지 않는 한 새 Markdown 파일에서 의미가 없을 것입니다. 마이그레이션된 콘텐츠에는 절대 링크(https://example.com/about)가 더 안전합니다.

이미지 경로를 확인하세요. Markdown의 이미지 참조는 접근 가능한 URL이나 로컬 파일 경로를 가리켜야 합니다. 마이그레이션 과정의 일부로 이미지 경로를 업데이트하세요.

변환 후 렌더링을 테스트하세요. 변환된 Markdown을 미리보기 도구에 붙여넣고 원본과 비교하세요.

실용적인 마이그레이션 워크플로우

소~중간 규모 블로그를 HTML CMS에서 Markdown 기반 정적 사이트로 마이그레이션하는 효과적인 워크플로우입니다:

1. 소스 CMS에서 콘텐츠 내보내기(대부분 내보내기 기능이 있음)
2. HTML 파일을 받으면 Turndown.js나 pandoc을 사용하는 스크립트로 일괄 변환
3. 1차 검토 — 명백한 변환 아티팩트 찾기
4. 깨진 이미지 경로와 링크 업데이트
5. 제목 구조 확인 및 계층 구조 문제 수정
6. 최종 Markdown 파일을 미리보기 도구로 렌더링 검토
7. 새 사이트로 가져오고 라이브 출력 확인

50개 게시물 블로그의 경우, 이 프로세스는 며칠이 아닌 몇 시간이면 완료됩니다.

변환하지 말아야 할 경우

모든 것을 Markdown으로 변환할 필요는 없습니다.

페이지에 복잡한 인터랙티브 컴포넌트가 있다면 — JavaScript 기반 탭, 아코디언, 동적 콘텐츠 — HTML 셸을 Markdown으로 변환하면 페이지를 작동시키는 바로 그것들이 제거됩니다.

정확한 시각적 포맷이 중요한 경우(랜딩 페이지, 마케팅 자료, 디자인된 기사 레이아웃), Markdown의 스타일링 제어 부재는 적합하지 않습니다.

Markdown은 텍스트가 많고 상대적으로 단순한 구조의 콘텐츠에 훌륭한 도구입니다. 더 복잡한 것에는 HTML이 종종 올바른 선택입니다.

마치며

HTML과 Markdown은 서로 다른 목적과 대상을 위해 존재합니다. HTML은 브라우저를 위한 것이고, Markdown은 브라우저에 올라갈 것을 작성하는 사람들을 위한 것입니다.

두 형식 사이의 변환은 해결된 문제입니다 — 도구들이 존재하고, 좋고, 무료입니다. 진짜 기술은 변환이 가치를 더하는 시점과 그렇지 않은 시점을 아는 것, 그리고 실제로 사용 가능하도록 출력물을 정리하는 방법을 아는 것입니다.

빠른 일회성 변환에는 HTML to Markdown 도구가 가장 빠른 방법입니다. 대규모 마이그레이션의 경우, 프로그래밍 방식의 접근법과 탄탄한 검토 프로세스를 결합하세요.

콘텐츠가 Markdown에 있게 되면, 왜 HTML로 계속 유지했는지 의아할 것입니다.