markdownify, 1.8 MiB에서 markitdown과 동일한 표 행 출력 수를 기록

markitdown과 함께 본 4개의 HTML 샘플에서 markdownify는 우리의 카운터 기준으로 생성된 Markdown 표 행 수가 똑같이 나왔습니다. 둘 다 36개였고, 확인 대상이었던 16개의 콘텐츠 문자열도 전부 복원했습니다. 출력 토큰 수는 21,062개로 명목상 가장 낮았지만, 앞선 세 변환기는 서로 1.3% 이내 차이였고요. 설치 용량은 1.8 MiB에 불과하고, MIT 라이선스를 사용하며, 스냅샷 시점 기준 GitHub 스타는 2,235개였습니다.

이 카테고리에서 제일 덜 알려진 라이브러리이긴 하지만, 적어도 이번 수치만 놓고 보면 제가 먼저 집을 도구는 이쪽입니다.

markdownify란?

markdownify는 BeautifulSoup 위에 올라간 Python용 HTML-to-Markdown 변환기입니다. 구조가 아주 단순합니다. BeautifulSoup으로 파싱하고, 트리를 훑으면서 Markdown을 뽑아냅니다. 테스트한 버전은 1.2.3이며, MIT 라이선스, 2,235개 스타, 42개의 열려 있는 이슈, 2026-06-30 마지막 릴리스 — 지금도 꽤 활발하게 관리되고 있고, 총 44번 릴리스되었습니다.

공식 참고 자료: python-markdownify's official repository.

API는 사실상 하나라고 봐도 됩니다.

from markdownify import markdownify
md = markdownify(html)

원하면 요소 처리 방식을 바꿀 수 있는 클래스 형태(MarkdownConverter)도 있고, 제목 스타일, 글머리표 문자, 코드 언어 감지, 요소 제거 같은 옵션도 제법 잘 갖춰져 있습니다. 그래도 가장 흔한 쓰임은 한 줄 호출이고, 실제로도 잘 돌아갑니다.

pip install markdownify를 실행하면 5개 패키지와 1.8 MiB가 설치되며, 콜드 임포트는 0.046초로, 제가 테스트한 세 변환기 중 가장 빨랐습니다. 의존성 구조는 BeautifulSoup와 보조 패키지들로 이루어져 있는데, 이미 많은 Python 프로젝트가 이 조합을 쓰고 있어서 추가 부담이 거의 없을 때가 많습니다.

측정 방식

이 베이스의 다른 패키지에서 이미 markitdown에 썼던 4개의 HTML 샘플을 대상으로 테스트했습니다. 여기에 그 패키지의 사전 등록된 검증 문자열도 함께 적용해서, 본문 문자열 16개가 살아남는지 확인했고, 페이지의 기본 골격 체크도 넣었습니다. 다섯 번째 샘플인 Nothing but tables는 표가 아주 많은 별도 진단용 케이스라서, 아래의 4개 샘플 종합값에서는 뺐습니다.

fourway-scores.json. 4개 샘플 기준이고, 토큰은 o200k_base로 계산했습니다. 표 행 수는 4개 샘플 전체에 같은 규칙을 적용해 세었고, 여기에는 markitdown의 저장된 출력 재계산도 포함됩니다. 그 값은 공개된 수치와 정확히 일치했습니다.

눈에 띄는 점은 세 가지입니다.

markitdown과 표 행 수가 같습니다. 4개 공통 샘플에서 둘 다 36행이었고, 같은 휴리스틱으로 셌습니다. 이게 셀 단위 완전 일치를 뜻하는 건 아닙니다. 다만 이 카운터 기준으로는 두 출력이 동일한 수의 인식 가능한 Markdown 표 행을 드러냈다는 뜻입니다.

토큰 수가 가장 적습니다. 21,062개로, html2text의 21,176개와 markitdown의 21,336개보다 조금 낮고, turndown의 26,236개보다는 19.7% 적습니다. 앞의 세 도구는 서로 1.3% 이내 차이라서, 저는 이걸 승리라기보다 사실상 동률로 봅니다. 진짜 차이는 turndown과의 격차에서 납니다.

모든 콘텐츠 검증 문자열이 통과했습니다. 16개 전부입니다. 나머지 세 도구도 마찬가지였으니, 콘텐츠 보존 자체는 이 라이브러리들 사이에서 큰 차이가 아니었습니다.

제대로 처리한 표

하키 통계 샘플에서는 변환기들 차이가 가장 또렷하게 드러납니다. markdownify는 다음처럼 출력합니다.

| Team Name | Year | Wins | Losses | OT Losses | Win % | ... |
| --- | --- | --- | --- | --- | --- | --- |
| Boston Bruins | 1990 | 44 | 24 |  | 0.55 | ... |

앞뒤 파이프가 있는 표준 GFM 형식에 구분 행이 들어가고, 24와 0.55 사이의 빈 셀도 그대로 보존됩니다. 빈 셀을 건너뛰지 않고 유지한다는 점이 중요합니다. 겉보기에는 사소해 보여도 전혀 사소하지 않습니다. 빈 셀을 지워버리는 변환기는 뒤의 모든 값을 한 칸씩 왼쪽으로 밀어버리는데, 결과물은 여전히 멀쩡한 표처럼 보이기 때문입니다.

turndown은 같은 입력에서 값을 열 구조 없이 문단처럼 흩뿌립니다. html2text는 스타일은 다르지만, 바깥쪽 파이프 없이도 올바른 표를 만듭니다.

Markdown이 모델로 들어간다면, 파이프와 빈 셀을 지켜야 “보스턴이 몇 경기를 졌는가” 같은 질문에 답할 수 있고, 그냥 감으로 때우지 않게 됩니다.

turndown이 하지 못하는 두 가지 제거

표 정확도는 눈에 보이는 차이입니다. 그런데 더 큰 차이는 따로 있고, 거의 언급되지 않습니다.

markdownify는 <script>와 <style> 내용을 제거합니다. turndown은 그렇지 않습니다. 해당 요소 안에서만 나오는 마커를 기준으로 세어보면, markdownify의 출력에는 샘플 전체에서 스크립트 마커 0개, 스타일 마커 0개가 들어 있습니다. 반면 turndown은 10개와 84개가 남습니다. Wikipedia 샘플에서는 이것이 59,561자와 74,939자의 차이를 만듭니다. 그리고 MediaWiki 인라인 JavaScript 설정과 CSS가 들어 있는 8줄이 무려 **14,644자, 즉 이 차이의 95%**를 차지합니다(script-style-stripping.json).

모델에 넣는 목적이라면, 이건 이번 비교에서 제일 큰 비용 항목입니다. JavaScript 설정 덩어리는 토큰만 잡아먹고 정보는 하나도 주지 않습니다. markdownify는 아무 말 없이 그걸 치워 줍니다. html2text도 마찬가지입니다.

샘플별로 보면, markdownify와 html2text는 표가 단순할 때는 딱 맞고, 복잡할 때는 갈립니다.

markdownify는 두 진단 비교 모두에서 더 많은 인식 가능한 행을 출력했습니다. 특히 Wikipedia에서는 이 카운터 기준으로 html2text의 5행보다 9행을 유지했습니다. 다만 이게 각 셀의 의미까지 전부 정확하다는 뜻은 아니므로, 복잡하고 비정형적인 표는 실제 예시로 꼭 확인해보는 게 좋습니다.

설치 용량과 라이선스를 다른 도구들과 비교하면

공식 참고 자료: markdownify on PyPI.

install-and-import.json 및 metadata-snapshot.json. 각 라이브러리는 서로 분리된 빈 환경에 설치했습니다.

html2text는 디스크 사용량이 9배 더 작지만, GPL-3.0-or-later 라이선스입니다. 배포형 제품이라면 라이선스 담당자가 이 부분을 꼭 봐야 합니다. 이 글은 법률 자문이 아닙니다. markdownify는 MIT라서 보통 더 느슨한 편이지만, 그래도 평소의 컴플라이언스 검토 대상에는 들어가야 합니다.

이미 BeautifulSoup를 쓰고 있다면 1.8 MiB라는 수치도 어느 정도는 이름뿐입니다. 많은 Python 스크래핑 프로젝트가 이미 BeautifulSoup를 쓰기 때문에, 그런 경우 markdownify의 추가 비용은 사실상 거의 없을 수 있습니다.

릴리스 주기는 세 도구 중 markdownify가 가장 건강합니다. 테스트 시점 6주 전에도 업데이트가 있었고, 총 44번 릴리스되었습니다. html2text는 마지막 릴리스가 2025년 4월이었습니다.

Python 한 줄로 실제로 얻는 것

이 라이브러리는 결국 markdownify(html) 한 줄입니다. 그런데 이 호출이 대신 결정해주는 것들을 분명히 짚어둘 필요가 있습니다. 이번 비교에서 핵심이 된 결정이 바로 그 3가지였기 때문입니다.

BeautifulSoup로 파싱하고, 요청하지 않아도 <script>와 <style>을 제거하며, 바깥 파이프와 보존된 빈 셀을 포함한 GFM 스타일 표를 출력합니다. 파서의 평판만으로는 잘못된 HTML에서의 동작이 보장되지 않아서, 그 부분은 아래에서 따로 측정했습니다.

이것들은 사용자가 따로 고른 옵션이 아닙니다. 기본 동작 그 자체입니다. 그리고 turndown의 기본값은 JavaScript를 그대로 남기고, html2text의 기본값은 78자에서 강제로 줄바꿈한다는 점을 생각하면, 별도 보정 없이 바로 쓸 수 있는 라이브러리는 그 자체로 가치가 있습니다.

원하면 옵션도 있습니다. heading_style, bullets, code_language, 요소 허용/차단을 위한 strip과 convert, 그리고 요소별 오버라이드를 위한 MarkdownConverter까지 제공합니다. 하지만 여기서 측정한 항목들은 전부 기본 옵션만 사용했습니다.

메모리와 깨진 HTML이 미치는 영향

더 넓은 스트레스 테스트 맥락은 10개 라이브러리의 메모리 및 비정상 HTML 비교에 있습니다.

이번 세트의 모든 리뷰에서 “미측정”으로 남아 있던 두 항목도 이제 측정했습니다.

피크 상주 메모리는 /usr/bin/time -l로 측정했고, 셀마다 새 프로세스를 하나씩 띄웠습니다. 임포트 하한은 라이브러리를 불러만 놓고 대기 상태일 때 드는 비용이고, 피크 값에는 문서 처리 비용이 포함됩니다.

memory-results.json. Python과 Node 기준값은 서로 직접 비교할 수 없습니다. 두 경우 모두 인터프리터가 포함되어 있기 때문입니다.

markdownify는 중간 정도 위치입니다. 임포트 하한은 23.9 MiB, 10 MB 문서에서 피크는 278.5 MiB였습니다. 이건 html2text 피크의 3.9배이고 turndown의 대략 10분의 1 수준인데, 그만큼 BeautifulSoup 기반으로 쓰는 대가라고 볼 수 있습니다.

깨진 HTML. 정확히 하나씩만 망가뜨린 문서 12개를 썼습니다. 닫히지 않은 태그, 잘못 중첩된 인라인 요소, 공백이 들어간 따옴표 없는 속성, 튀어나온 닫는 태그, <html> 자체가 없는 문서, 중복 속성, 태그 도중 잘린 문서, 잘못된 엔티티, 닫히지 않은 <script>, 거짓 charset 선언, 마크업이 들어간 주석, 그리고 600단계 중첩입니다. 여기에 크기가 맞는 정상 문서 2개도 추가했는데, “아무것도 돌려주지 않았다”는 말은 라이브러리가 정상 문서에서도 침묵할 때만 비정상성을 뜻하기 때문입니다.

markdownify는 14개 중 1개에서 예외를 냈고, 아무것도 반환하지 않은 경우는 0개였으며, 깨진 샘플들에서 33개 중 30개의 시그널을 복원했습니다(malformed-results.json). 한 샘플은 이 집계에서 제외했습니다. HTML5 규칙상 닫히지 않은 <script> 뒤의 모든 것은 script 내용으로 간주되므로, 그 안에서 내용을 잃는 건 올바른 동작이고, 복원되는 쪽이 오히려 규칙에서 벗어납니다.

장단점

장점. markitdown과 같은 표 정확도, 같은 기준으로 계산함. 4개 중 토큰 수 최저. MIT. 1.8 MiB이고, 이미 BeautifulSoup가 있다면 추가 비용이 거의 없음. 콜드 임포트 0.046초로 가장 빠름. 활발히 업데이트됨. 빈 표 셀을 보존함. MarkdownConverter로 요소별 변환을 오버라이드할 수 있음. 기본 한 줄 호출이 거의 정답에 가깝다.

단점. BeautifulSoup에 의존해서, 이미 가지고 있지 않다면 html2text보다 디스크 사용량이 9배 큼. 스타 2,235개는 turndown보다 커뮤니티가 작다는 뜻이고, 이상한 입력을 만났을 때 참고할 예제가 더 적을 수 있음. Python 전용이라 Node 스택에는 도움이 되지 않음. 그리고 열려 있는 이슈가 42개.

누가 써야 하고, 누가 피해야 하나

이 샘플들과 비슷한 입력을 다루는 Python 작업이라면 markdownify부터 시작하세요. 이 카운터 기준으로 markitdown과 표 행 수가 같고, 토큰 수는 최저권이며, MIT 라이선스입니다. 이미 BeautifulSoup에 의존한다면 추가 설치 부담이 작을 수 있으니, 실제 환경에서 의존성 증가분을 확인해보는 게 좋습니다.

의존성 예산이 수백 KB 단위로 빡빡하고, 출력 형태가 현재 페이지들에 잘 맞는다면 html2text도 고려할 만합니다. 다만 배포 전에 라이선스 담당자와 함께 GPL-3.0-or-later를 검토해야 합니다.

이미 PDF나 Office 문서를 Markdown으로 바꾸고 있다면 markitdown도 고려할 수 있습니다. 여기서는 HTML 결과의 표 행 수가 같았지만, 더 넓은 의미의 정확도가 같다는 증거는 없었습니다.

Node 환경이라면 건너뛰세요. 그 경우에는 turndown-plugin-gfm을 함께 설치한 turndown이 자연스러운 선택입니다. turndown의 핵심만으로는 표를 전혀 만들지 못하기 때문입니다.

관리형 API는 어디에 맞나

markdownify는 이미 가지고 있는 HTML을 변환합니다. 가져오지도 않고, JavaScript도 렌더링하지 않으며, 봇 차단 계층도 처리하지 않습니다. 사실 네 개의 변환기 모두 그렇고, 실제 대상에서는 그 앞단 작업이 더 어려운 경우가 많습니다.

다섯 개 변환기를 같은 샘플에 적용한 결과는 HTML-to-Markdown 5개 도구 비교에서 볼 수 있습니다.

Thunderbit의 개발자 스택은 바로 그 앞단 작업을 해결합니다. POST /distill은 URL을 가져와 Markdown을 반환하고, POST /extract는 스키마 형태의 JSON을 반환합니다. 둘 다 MCP 서버와 CLI로 사용할 수 있으며, 요금은 Thunderbit 가격 페이지에서 확인할 수 있습니다. 이 호스티드 엔드포인트들은 이번 로컬 변환기들과 직접 벤치마크한 게 아니므로, 성능 비교가 아니라 카테고리 구분으로 이해하면 됩니다.

솔직히 말하면 이렇습니다. HTML을 이미 갖고 있고 Markdown만 필요하다면, markdownify는 무료이고 이 일을 꽤 잘합니다. 페이지를 가져와야 하거나 문단이 아니라 행 단위 결과가 필요하다면, 그건 또 다른 구매 판단입니다.

더 넓은 시장을 보고 싶다면 웹 스크래핑 API 종합 가이드에서 호스티드 옵션을, 오픈소스 스크래퍼 종합 글에서 자체 호스팅 옵션을 확인할 수 있습니다. Python에서 HTML을 Markdown으로 변환하기는 실전용 안내서입니다.

웹 데이터 추출을 위해 Thunderbit 체험하기

markdownify를 써야 할까?

Python 환경이고, 입력이 이 샘플들과 비슷하다면 충분히 강한 후보입니다. 다만 기본값으로 쓰기 전에, 본인의 표와 비정상 HTML에서 먼저 시험해보세요.

이 카운터 기준으로 markitdown과 표 행 수가 같고, 토큰 수는 최저권이며, 이번 실행에서 가장 빨리 임포트됐고, MIT 라이선스입니다. 반대로 html2text보다 메모리를 더 썼고, Python 전용이며, 비정상 입력 샘플 하나에서 예외를 냈습니다. 디스크 사용량과 라이선스도 선택 기준이지만, 전부는 아닙니다.

제가 특히 눈여겨본 건 스타 수입니다. turndown은 관심도가 5배나 높지만, 기본 상태에서는 markdownify가 제대로 처리하는 표를 하나도 변환하지 못합니다. 이 카테고리에서는 인기가 실제 동작을 따라가지 못하고 있고, 그 점이 바로 이번 비교를 해볼 만했던 이유이기도 합니다.

웹 데이터 추출을 위해 Thunderbit 체험하기 Get Started Free

자주 묻는 질문

markdownify는 HTML에서 정말 markitdown만큼 좋은가요? 이번 4개 샘플에서는 둘 다 인식 가능한 Markdown 표 행 36개를 출력했고, 확인 대상 문자열 16개를 모두 복원했으며, 문자 수 기준 출력 차이도 0.2% 이내였습니다. 다만 이건 셀 단위나 렌더링 완전 일치 테스트는 아닙니다. 또 markitdown은 PDF와 Office 형식도 처리하므로, 이 비교는 오직 측정한 HTML 출력에 대한 것입니다.

BeautifulSoup가 꼭 필요한가요? 네. 이 라이브러리의 파서이고, 1.8 MiB 대부분을 차지합니다. 프로젝트가 이미 BeautifulSoup를 쓰고 있다면 markdownify의 추가 비용은 작습니다. 아니라면, 디스크가 정말 중요할 때는 패키지 1개, 0.2 MiB인 html2text를 볼 수 있지만, 대신 GPL-3.0-or-later 라이선스가 붙습니다.

빈 표 셀은 어떻게 처리하나요? 그대로 출력합니다. 데이터가 비어 있는 샘플에서도 빈 셀 위치를 유지해서, 뒤의 값들이 올바른 열에 남아 있습니다. 빈 셀을 건너뛰는 변환기는 여전히 멀쩡해 보이지만, 모든 값이 한 칸씩 왼쪽으로 밀린 표를 만들어내는 더 나쁜 실패를 합니다.

함수와 클래스를 중 뭐를 써야 하나요? 보통은 markdownify() 함수를 쓰면 됩니다. 특정 요소의 변환 방식을 바꿔야 할 때는 MarkdownConverter를 쓰세요. 여기서 측정한 모든 항목은 기본 옵션의 함수 버전으로 테스트했습니다.

이번 글에서 테스트하지 않은 것은 무엇인가요? 4개 공통 샘플과 표 전용 진단 1개만으로는 대표 코퍼스라고 보기 어렵습니다. 별도의 비정상 HTML 세트는 12가지 고장 유형과 2개의 정상 비교군을 다뤘지만, 깨진 HTML의 모든 형태를 포함하진 않았습니다. 중첩 목록, 정의 목록, 각주, 수식, Markdown-to-HTML 왕복, 셀 단위 표 동일성, 설정 변형은 비교하지 않았고, 변환 속도도 비교하지 않았습니다.