[GitHub 탐방] markitdown으로 논문 PDF를 md로 바꿔서 Claude한테 먹이려다가

YellowBigRoot·2026년 4월 14일

GitHub 탐방

목록 보기

2/5

microsoft/markitdown · ⭐ 주 13k · Python
"Python tool for converting files and office documents to Markdown"

왜 이걸 보게 됐나

지난 주에 LLM4TS 회의론 재평가 논문 리뷰를 쓰면서 한 가지 병목이 계속 걸렸다. 논문 PDF에서 본문·수식·표를 "Claude에 먹이기 좋은 형태"로 뽑는 일이 그 자체로 귀찮다는 것. 매번 Claude에 PDF를 그대로 업로드해도 되긴 하지만, 내 손에 md 파일이 있으면 SESSION.md처럼 다른 문서와 같이 grep하고 인용할 수 있고, 블로그 초안에 섹션 단위로 복붙하기도 훨씬 편하다. 그래서 "PDF → md 파이프라인"을 하나 만들고 싶었다.

마침 GitHub 트렌딩에 microsoft/markitdown이 이번 주 내내 상위에 떠 있었다. 한 줄 설명이 "Python tool for converting files and office documents to Markdown". PDF·docx·pptx·xlsx·이미지·오디오·유튜브 자막·EPub까지 지원하고, CLI 한 줄(markitdown file.pdf -o out.md)이면 끝이라고 한다. 별이 주간 13k+면 어느 정도 검증됐다고 봐도 될 것 같았다.

결론부터 말하면, 내 유즈케이스(2-column 학술 PDF)에는 가장 안 맞았다. 이게 markitdown의 결함이라는 뜻은 아니고, 한 편의 논문을 돌려본 뒤 그 구조적 이유까지 추적했다는 이야기다. 이 글은 그 단일 실험 기록이다.

실험 설계

대상 PDF: arXiv 2602.14744 Rethinking the Role of LLMs in Time Series Forecasting — 직전 글에서 리뷰한 논문을 그대로 재활용했다. 16페이지, 2-column, 본문에 수식·참고문헌·몇 개의 표가 섞여 있는 평범한 학회 논문 포맷이다.
비교군: 논문 PDF 변환에서 흔히 쓰이는 두 가지.
- pymupdf4llm — PyMuPDF 기반, LLM 친화 md 출력을 목표로 만들어진 라이브러리.
- pdftotext (poppler-utils) — 클래식. -layout/기본 두 모드 모두 측정.
실행: 네 도구로 같은 PDF를 변환하고 (1) 시간 (2) 파일 크기 (3) 본문/표/참고문헌 영역의 품질을 관찰.

pip install 'markitdown[pdf]' pymupdf4llm
# pdftotext는 poppler-utils에 포함

markitdown rethinking-llms.pdf -o outputs/markitdown.md
python -c "import pymupdf4llm; open('outputs/pymupdf4llm.md','w').write(
    pymupdf4llm.to_markdown('rethinking-llms.pdf'))"
pdftotext -layout rethinking-llms.pdf outputs/pdftotext.txt
pdftotext          rethinking-llms.pdf outputs/pdftotext-raw.txt

결과 수치

도구	시간	크기	라인 수	`
markitdown 0.1.5	3.5s	176KB	2151	918
pymupdf4llm 1.27	6.5s	120KB	1172	267
pdftotext -layout	0.1s	182KB	1990	—
pdftotext (reading)	0.1s	111KB	4579	—

가장 눈에 띄는 숫자가 오른쪽 끝의 918이다. 원 논문에는 표가 몇 개 없는데 markitdown은 markdown 표 셀 기호(|)로 시작하는 라인을 918줄이나 뽑아냈다. 거의 절반이 가짜 표라는 뜻이다.

markitdown 출력 — 2-column 오인식 참사

Abstract 첫 부분을 잘라보면 바로 보인다.

|     |     | Rethinking |     | the | Role | of LLMs | in Time | Series | Forecasting |
| --- | --- | ---------- | --- | --- | ---- | ------- | ------- | ------ | ----------- |
XinQiu12 JunlongTong1 YirongSun1 YunpuMa3 WeiZhang1 XiaoyuShen1
|       |          |        | Abstract |        |      |          | decadesofresearchonstatistical... |
...
| Large | language | models |          | (LLMs) | have | been in- |  |  |  |
| -------- | --- | ------- | ------------------ | --- | ----- | ------ | ---...
| corporatecontextualknowledgebeyondnumer-

세 가지 문제가 겹쳐 있다.

2-column을 표로 오인식. 왼쪽 컬럼 한 줄과 오른쪽 컬럼 한 줄이 비슷한 y좌표에 있으면, 그걸 "한 행의 두 셀"로 묶어 markdown 표를 생성해 버린다. 본문 절반 이상이 이 패턴에 걸렸다.
단어 단위 띄어쓰기 유실. accurateTSFremainschalleng- 같은 식으로 인접한 글자들이 공백 없이 병합된다. 토크나이저 입장에선 모르는 단어 덩어리가 된다.
섹션 헤더가 없음. # Introduction, ## 3. Experiments 같은 마크업이 한 번도 등장하지 않는다. 제목과 본문의 경계가 사라진다.

참고문헌 영역은 더 심하다. 저자명과 연도가 두 칼럼을 오가며 섞이고, 한 줄짜리 인용이 4~5개 셀로 쪼개진 가짜 표가 수백 줄 이어진다. 이걸 Claude에 넣고 "이 논문 인용 목록 정리해줘"라고 하면 컨텍스트 낭비는 물론이고 답도 망가질 가능성이 높다.

왜 이렇게 되는가 — pdfminer.six 백엔드

원인을 찾으려고 설치된 패키지를 뒤졌다.

$ pip show markitdown
Name: markitdown
Version: 0.1.5
Requires: beautifulsoup4, charset-normalizer, defusedxml, magika, markdownify, requests

markitdown 본체의 의존성에는 PDF 라이브러리가 없다. [pdf] extra를 깔 때 딸려오는 의존성을 보면 pdfminer.six가 있다. 즉 markitdown의 PDF 처리는 전적으로 pdfminer.six에 위임돼 있고, markitdown은 pdfminer 결과를 markdownify로 후처리해 md로 바꾸는 얇은 레이어다. README엔 이 사실이 명시돼 있지 않다.

pdfminer.six는 PDF 텍스트 추출 자체는 정확하지만 레이아웃 분석이 약하다. 특히 2-column 학술 논문을 넘겨주면 y좌표 기반으로 블록을 묶느라 좌우 컬럼을 종종 한 행으로 취급한다. markitdown이 그 위에 "이 블록들을 표로 변환하자"는 휴리스틱을 얹으니 결과가 증폭돼 앞에서 본 참사가 된다.

요약하면 이번 실험의 실패는 markitdown 자체의 버그라기보단 백엔드 선택의 결과다. 이 진단이 중요한 이유는, 논문이 아닌 다른 PDF(1-column 보고서, 슬라이드 export, 블로그 PDF 등)에서는 문제가 한참 덜할 수도 있다는 말이기도 하기 때문이다.

pymupdf4llm 출력 — 압도적

같은 논문, 같은 명령 한 줄.

import pymupdf4llm
md = pymupdf4llm.to_markdown("rethinking-llms.pdf")

첫 부분을 잘라 보면 분위기가 완전히 다르다.

**Rethinking the Role of LLMs in Time Series Forecasting**

## **Xin Qiu** [1 2] **Junlong Tong** [1] ...

## **Abstract**

Large language models (LLMs) have been introduced to time series
forecasting (TSF) to incorporate contextual knowledge beyond numerical
signals. However, existing studies question whether LLMs provide
genuine benefits, often reporting comparable performance without LLMs.
We show that such conclusions stem from limited evaluation settings
and do not hold at scale. ...

2-column 리딩 순서가 정확하다. Abstract가 한 문단으로 묶인다.
**bold**, _italic_ 강조가 살아 있다. 이게 왜 중요하냐면, 이 논문은 Pre-alignment outperforms post-alignment in over 90% of tasks 같은 핵심 주장에 이탤릭을 쓰는데, 강조가 유지되면 LLM이 "여기가 저자가 강조한 지점"이라는 신호를 그대로 받을 수 있다.
섹션 제목에 ## **1. Introduction** 식으로 레벨이 붙는다. 목차화가 가능해진다.
참고문헌이 - Author, ... 리스트로 변환된다. 그대로 BibTeX 파싱기에 넘길 수 있는 수준은 아니지만, markitdown의 가짜 표보단 비교할 수 없이 낫다.

약점도 기록해 둔다. 수식( $X \in \mathbb{R}^{N \times M}$ 같은 inline math)은 plain text로 flatten된다. 그림 본체는 당연히 사라지고 캡션만 남는다. 즉 수식과 그림이 핵심인 논문이라면 이 파이프라인 결과만 보고 리뷰를 쓸 순 없고, 해당 부분은 arXiv HTML판을 열어서 직접 캡쳐해야 한다. 내가 003 글에서 수식과 Figure 1을 직접 다시 정리했던 이유와 정확히 같은 맥락이다.

pdftotext — 클래식은 클래식인 이유가 있다

두 가지 모드 모두 0.1초 안에 끝난다. 빠르기는 압도적.

-layout 모드는 PDF 뷰어처럼 공백으로 시각적 2-column 배치를 재현한다. 사람 눈으로는 읽히지만, 텍스트 줄로 보면 왼쪽 컬럼과 오른쪽 컬럼이 같은 줄에 섞여 LLM에 넣기엔 좌우가 뒤섞인 난장판이 된다.
기본(no -layout) 모드는 리딩 순서가 그나마 맞지만, 헤더·강조가 전혀 없어 그냥 평문 덩어리다.

요약: md 파이프라인에는 부적합. grep으로 특정 단어 있나만 확인할 때 쓰는 도구다.

정리 — 언제 뭘 쓸 것인가

단 한 편의 PDF, 그것도 2-column 학술 논문에 한정한 결과지만 내 워크플로우에 적용할 규칙은 분명해졌다.

학술 PDF → md: pymupdf4llm. 논문 리뷰 글을 쓸 때 본문을 md로 확보하는 용도로 이번 주부터 이걸 쓰기로 했다.
docx / pptx / xlsx / 이미지 OCR / 유튜브 자막 등 잡다한 입력: 여전히 markitdown이 후보다. 이번 실험은 PDF extra 하나만 때렸고, markitdown이 원래 잘하는 구역(office 문서)은 전혀 테스트하지 않았다. "markitdown은 별로다"라고 말하면 안 되는 이유가 이것이다.
빠른 확인: pdftotext. "이 논문에 routing 단어 나오나?" 정도는 여전히 이게 제일 빠르다.

이번 실험의 한계

정직하게 적어 두는 캐비엇.

표본 N=1. 논문 한 편이다. 다른 레이아웃(1-column, 워크숍 포맷, 테크니컬 리포트)에서는 결과가 다를 수 있다.
수식/그림: 어느 도구도 본격적으로 복원하지 않는다. 이번 실험은 "본문이 얼마나 깨끗하게 나오나"만 봤다. 수식 보존을 원하면 nougat, mathpix, marker 같은 다른 계열을 따로 봐야 한다.
markitdown의 주력 포맷(docx/pptx/xlsx)은 테스트 안 했다. 이 글의 결론을 그 구역까지 일반화하면 안 된다.
markitdown 플러그인 / LLM 옵션: markitdown은 이미지 설명에 LLM 클라이언트를 붙일 수 있지만(llm_client=OpenAI()), 이번엔 PDF라 해당 없음. plugin 기능도 켜지 않았다.