HTML 마크다운 변환이 완벽하지 않은 이유

HTML 문서를 마크다운으로 바꿔서 노션이나 깃허브, 정적 사이트 원고로 옮겨본 적이 있다면 한 번쯤 마주치는 장면이 있습니다. 원본에서는 표 안에 두 칸이 하나로 합쳐져 있었는데, 변환된 마크다운을 열어보면 그 병합은 물론 표 모양 자체가 사라지고, 칸에 있던 글자만 줄줄이 나열되어 있습니다. 글자에 입혀뒀던 색깔도 마찬가지로, 변환 후에는 색 정보 없이 그냥 검은 글자로 남습니다.

이건 변환이 잘못됐다는 신호가 아닙니다. 마크다운이라는 포맷 자체가 그런 정보를 담을 문법을 애초에 갖고 있지 않기 때문에 생기는, 구조적으로 당연한 결과입니다.

요약 ① 마크다운은 굵게·기울임·목록·표 같은 기본적인 문서 서식만 표현하도록 설계된 단순한 포맷이라, HTML의 정교한 기능에 대응하는 문법 자체가 없는 경우가 많습니다. ② 병합된 표 셀, 특정 글자 색, 중첩된 인라인 스타일처럼 마크다운에 대응 문법이 없는 정보는 변환 과정에서 사라지거나 다른 형태로 뭉개집니다. ③ 그래서 변환 결과는 그대로 믿지 말고, 표와 색상·강조가 들어간 구간을 중심으로 눈으로 직접 확인하는 과정이 항상 필요합니다.

마크다운은 원래 무엇을 표현하려고 만들어진 포맷인가

마크다운은 사람이 손으로 쓰기 쉬운 평문에 최소한의 기호만 더해서, 제목·굵게·기울임·목록·인용·링크·코드 정도의 기본 서식을 표현하도록 설계된 포맷입니다. 문법표 하나로 전체 규칙을 정리할 수 있을 만큼 기호의 종류 자체가 적습니다.

반면 HTML은 태그마다 다양한 속성을 가질 수 있고, 여기에 CSS까지 더해지면 색상·크기·정렬처럼 사실상 제한이 거의 없는 조합의 표현이 가능합니다. 두 포맷은 애초에 표현하려는 범위 자체가 다릅니다.

그래서 HTML을 마크다운으로 옮기는 작업은 "번역"이라기보다 "요약"에 더 가깝습니다. 마크다운 문법에 대응하는 표현이 있는 정보만 옮겨지고, 대응 문법이 없는 정보는 변환 과정에서 자연스럽게 빠지게 됩니다.

HTML에는 있지만 마크다운 문법에는 없는 것들

가장 자주 걸리는 경우가 표의 병합 셀입니다. HTML 표는 한 칸이 가로로 여러 칸을 차지하거나(colspan) 세로로 여러 행을 차지하도록(rowspan) 만들 수 있습니다. 하지만 마크다운 표 문법은 제목 행과 구분선(---) 행, 그 아래 데이터 행들이 전부 같은 칸 수를 가져야 하는 단순한 격자 구조뿐이라, 칸이 합쳐진다는 개념 자체가 문법에 없습니다.

색상과 인라인 스타일도 마찬가지입니다. HTML은 style 속성이나 class로 글자색·배경색·글꼴 크기를 자유롭게 지정할 수 있지만, 마크다운에는 굵게·기울임·취소선·인라인 코드 정도의 몇 가지 강조 기호만 있을 뿐 색이나 크기를 지정하는 문법이 아예 없습니다.

이 도구의 "제목 스타일" 옵션에서도 비슷한 사정을 볼 수 있습니다. 밑줄로 제목을 표시하는 Setext 방식은 마크다운 문법 자체에 1단계(=)와 2단계(-), 딱 두 단계만 정의되어 있습니다. 그래서 원본 HTML에 3단계 이상의 제목(h3~h6)이 있으면, Setext 스타일을 골라도 그 구간만은 자동으로 #(ATX) 표기로 바뀌어 나옵니다. 애초에 밑줄로 표현할 방법이 없는 단계를 억지로 밑줄에 욱여넣지는 않는다는 뜻입니다.

표를 옮길 때 특히 자주 깨지는 이유

마크다운 표 문법이 지원하는 건 왼쪽·가운데·오른쪽 정렬 정도입니다. 구분선 행에 콜론(:)을 어느 쪽에 붙이느냐로 정렬만 표현할 뿐, 세로 정렬이나 셀 배경색, 셀 병합 같은 정보를 담을 자리는 문법에 없습니다.

그런데 이 도구가 실제로 하는 일은 그보다 더 단순합니다. HTML 표를 파이프(|) 기호로 짜인 마크다운 표 문법으로 다시 구성해 주지는 않고, 칸 하나하나에 있던 글자만 순서대로 문단으로 풀어놓습니다. 그래서 표가 있던 자리에는 줄과 칸으로 구분된 표 모양 대신, 칸 내용이 위에서 아래로 나열된 여러 개의 문단만 남습니다. 표가 있는 글일수록 변환 후 한 번 더 확인해야 하는 이유입니다.

직접 해보기 →

이 도구가 자동으로 처리해 주는 부분

HTML → 마크다운 변환 도구는 입력창에 HTML을 붙여넣는 순간 마크다운 문법으로 대응이 가능한 부분(제목·굵게·링크·목록·코드 블록 등)을 자동으로 옮겨줍니다. 별도의 "변환" 버튼을 누를 필요 없이, 입력이 바뀌면 결과가 곧바로 갱신됩니다.

제목 스타일(ATX # 또는 Setext 밑줄), 목록 기호(하이픈·별표·플러스), 코드 블록 스타일(펜스 또는 들여쓰기)도 선택할 수 있어서, 옮겨 붙일 곳의 마크다운 관례에 맞춰 형식을 고를 수 있습니다. 이 과정은 붙여넣은 순간 브라우저 안에서만 계산되고 서버로는 전송되지 않습니다.

다만 이 자동화가 하는 일은 "마크다운 문법에 있는 것을 정확히 옮기는 일"까지입니다. 표를 파이프 문법으로 다시 짜주거나, 마크다운에 아예 없는 문법(셀 병합, 색상)을 만들어낼 수는 없으니, 그 지점은 결과를 눈으로 보고 직접 판단해야 합니다.

변환 후 우선적으로 확인할 지점

표가 있었다면 칸 내용이 놓인 순서부터 살펴봐야 합니다. 표 모양은 사라지고 문단으로 풀리기 때문에, 원본에서 같은 줄에 있던 칸들의 내용이 순서대로 이어지는지, 아니면 엉뚱한 자리로 밀려서 뜻이 달라졌는지를 확인합니다.

색이나 배경으로 강조했던 구간도 다시 봐야 합니다. 변환 결과에는 그 강조가 굵게나 기울임 같은 다른 기호로라도 남아있는지, 아니면 아무 표시 없이 평범한 문장으로 묻혀버렸는지가 갈립니다. 강조가 사라진 자리는 붙여넣을 곳에서 손으로 다시 표시해 주는 편이 안전합니다.

정리

• 마크다운은 기본적인 문서 서식만 표현하도록 설계된 단순한 포맷이라, HTML의 정교한 기능에 대응하는 문법 자체가 없는 경우가 많습니다.
• HTML 표는 마크다운의 표 문법(파이프 기호)으로 다시 구성되지 않고, 칸 내용이 순서대로 나열된 문단으로 풀립니다. 병합된 칸일수록 순서가 헷갈리기 쉽습니다.
• 글자 색·배경색 같은 인라인 스타일은 마크다운에 지정 문법이 아예 없어 변환 후 그대로 사라집니다.
• Setext 제목 방식은 1·2단계만 정의돼 있어, 그보다 깊은 제목 구조를 표현할 문법 자체가 없습니다.
• 이 도구는 대응 가능한 서식은 자동으로 옮겨주지만 문법이 없는 정보까지 만들어낼 수는 없으므로, 변환 후 표와 강조 구간은 직접 확인해야 합니다.

자주 묻는 질문

HTML 표에 있던 병합 셀은 변환 후 어떻게 되나요?

마크다운 표 문법에는 칸을 합친다는 개념 자체가 없습니다. 게다가 이 도구는 표를 마크다운의 표 문법(파이프 기호)으로 다시 짜주지 않고, 칸 하나하나의 글자만 순서대로 문단으로 풀어놓습니다. 그래서 병합돼 있던 칸이든 아니든 표 모양 자체가 사라지고, 칸 내용이 줄줄이 나열된 문단만 남습니다. 표가 포함된 HTML을 변환했다면 칸 내용의 순서와 뜻이 원본과 맞는지 반드시 확인해야 합니다.

글자 색이나 배경색을 넣었는데 변환 후 사라졌습니다. 왜 그런가요?

마크다운에는 색을 지정하는 문법이 애초에 없기 때문입니다. 굵게·기울임·취소선·인라인 코드 정도의 강조 기호만 존재하므로, 색이나 글꼴 크기 같은 정보는 변환 과정에서 옮길 자리가 없어 사라집니다. 강조가 꼭 필요하다면 변환 후 굵게나 기울임 같은 마크다운 기본 기호로 다시 표시해야 합니다.

제목이 3단계 이상인데 밑줄(Setext) 스타일을 고르면 어떻게 되나요?

Setext 방식은 마크다운 문법 자체에 1단계(=)와 2단계(-) 두 가지만 정의돼 있습니다. 이 도구는 3단계 이상의 제목(h3~h6)까지 밑줄로 억지로 표현하지 않고, 그 구간만 자동으로 #(ATX) 표기로 바꿔서 출력합니다. 그래서 Setext를 선택해도 제목 단계 자체는 유지되며, 다만 한 문서 안에 밑줄 표기와 # 표기가 섞여 나올 수 있습니다.

변환한 HTML이 서버에 저장되거나 전송되나요?

붙여넣은 HTML은 브라우저 안에서만 변환되고 서버로 전송되지 않습니다. 결과로 나온 마크다운도 화면의 결과창에만 표시되며, 복사 버튼으로 클립보드에 옮겨 쓰는 방식입니다.