HTML → Markdown 변환

HTML → Markdown 변환

웹 문서를 Markdown으로 변환할 때 구조와 노이즈를 어떻게 다루는가.

Scope

핵심 질문

HTML을 Markdown으로 변환할 때 단순 tag 치환을 넘어 어떤 구조·노이즈 문제를 처리해야 하는가?

Research

핵심 근거

• HTML은 layout과 interaction을 포함하고 Markdown은 문서의 의미 구조에 초점을 둔다.
• 본문 추출과 HTML-to-Markdown 변환은 별개의 문제다.
• 표, nested list, code block, link, image와 custom component는 정보손실 규칙이 필요하다.

참고 자료

• CommonMark specification: https://spec.commonmark.org/

Draft

HTML → Markdown 변환은 태그 이름을 Markdown 기호로 바꾸는 작업보다 복잡하다. HTML 페이지에는 본문 외에 navigation, 광고, 버튼, footer와 script가 섞여 있고 Markdown은 이를 표현할 방법도 필요도 없다.

먼저 본문을 골라야 한다

페이지 전체 DOM을 그대로 변환하면 menu와 cookie banner까지 Markdown에 들어온다. 그래서 readability extraction과 Markdown conversion을 분리하는 것이 좋다.

먼저 의미 있는 article 영역을 선택하고 그 안의 HTML만 변환한다.

구조 보존

heading, paragraph, emphasis, list, code와 blockquote는 비교적 자연스럽게 대응한다.

어려운 부분은 nested list, 복잡한 table, figure/caption, interactive widget이다. Markdown 표현력이 부족한 경우 HTML을 일부 유지하거나 정보를 단순화해야 한다.

링크와 이미지

상대 URL은 HTML의 <base href>가 있으면 검증된 유효 문서 base URL을, 없으면 최종 응답 URL을 기준으로 absolute URL로 정규화한다. 결과 링크나 후속 fetch에는 허용한 URL scheme과 목적지 검증을 적용한다.

이미지는 alt text와 source를 보존하되 lazy-loading용 data-src처럼 실제 URL이 다른 attribute에 들어가는 경우도 처리해야 한다.

코드

pre/code 영역의 공백과 language metadata를 보존하지 않으면 코드가 깨질 수 있다. 일반 텍스트 normalize 규칙을 code block에 그대로 적용해서는 안 된다.

핵심

좋은 HTML → Markdown 변환은 syntax conversion이 아니라 콘텐츠 정제 pipeline이다. 본문 추출, URL 정규화, 구조 변환, 표현 불가능한 요소의 fallback 정책을 함께 설계해야 한다.