MarkItDown 2026 — PDF·PPTX·HTML을 LLM용 markdown으로 바꿀 때 어디까지 믿어도 될까

Posted on by

PDF를 LLM에 넣었는데 문장은 살아 있는데 표가 흐트러지고, 슬라이드는 읽히는데 레이아웃이 다 눌려버리는 경험, 한 번쯤 했을 거다.

이럴 때 사람은 보통 두 갈래로 간다.

한쪽은 그냥 OCR 더 센 걸 붙이면 되겠지 로 가고,

다른 한쪽은 애초에 문서 전처리란 건 다 엉망이야 로 간다.

MarkItDown이 재밌는 건 그 중간쯤에 있기 때문이다.

문서를 예쁘게 다시 만드는 도구라기보다, LLM이 읽기 좋은 텍스트 구조를 빠르게 뽑아내는 데 집중한다.

이 차이를 이해하고 쓰면 꽤 유용하고, 반대로 그냥 “PDF to markdown 끝판왕” 정도로 기대하면 초반부터 살짝 삐끗한다.

2026년 4월 14일 기준으로 Microsoft의 markitdown README는 이 도구를 “LLM과 텍스트 분석 파이프라인용 markdown 변환기” 에 가깝게 설명한다.

즉, 사람 눈에 완벽한 재현보다 헤딩, 리스트, 표, 링크 같은 구조를 토큰 친화적으로 보존하는 쪽이 목표다.

이 글은 README를 다시 읽고, 같은 날 로컬에서 PDF와 PPTX를 직접 변환해본 결과를 기준으로, MarkItDown을 어디까지 믿어도 되는지, 그리고 언제 다른 선택지를 같이 봐야 하는지 정리한 메모다.

답부터 적으면

MarkItDown은 문서를 사람에게 다시 배포할 markdown 을 만드는 도구로 보기보다, LLM이 먹기 좋은 중간 레이어 를 만드는 도구로 보면 훨씬 만족도가 높다.

PDF와 PPTX 모두 본문 텍스트를 꽤 잘 끌어오고, 섹션 구조도 어느 정도 남는다.

대신 페이지 번호, 폼피드 문자, 슬라이드 레이아웃 붕괴, 도형 기반 배치 손실 같은 문제는 생각보다 빨리 보인다.

그래서 내 기준은 단순하다.

  • RAG 전처리
  • 문서 요약 입력
  • 에이전트 검색용 캐시
  • “원문 전체를 그냥 읽히게 만드는 일”

이런 용도라면 충분히 볼 만하다.

반대로 배포용 문서, 정밀 표 복원, 시각 배치가 중요한 발표자료, 법률 문서의 완전 동일 재현처럼 형태 보존이 핵심이면 기본 설정만으로는 부족하다.

이런 워크플로에선 바로 체감한다

  • PDF를 그대로 프롬프트에 던지기보다 markdown으로 한 번 정리해서 넣고 싶은 사람
  • 슬라이드, 워드, HTML, CSV가 섞인 인풋을 한 파이프라인으로 통일하고 싶은 사람
  • Obsidian, 위키, RAG, 에이전트 메모리 레이어에 원문을 얇게 적재하고 싶은 사람
  • “예쁘게 보기”보다 “잘 읽히기”가 중요한 운영자
  • MCP 서버나 배치 전처리 단계에서 문서 변환을 자동화하고 싶은 사람

문서 자체를 지식 레이어로 굴리는 방식은 LLM Wiki 2026 — RAG 안 붙이고도 개인 위키가 굴러가는 조건, second brain 운영 체크리스트 쪽과 바로 이어지고,

문서 변환을 에이전트 도구로 붙일지 더 얇은 wrapper로 끝낼지는 GUI 앱에 AI 에이전트 붙일 때 CLI wrapper가 먼저인 이유 2026 — MCP보다 얇은 하네스가 나은 순간 글과 같이 보면 판단이 쉬워진다.

2026년 4월 14일에 직접 돌려본 결과

이번 테스트는 딱 화려하지 않게, 지금 바로 현업 노트 파이프라인에 붙일 수 있는 수준만 봤다.

환경은 이랬다.

  • 날짜: 2026-04-14 KST
  • Python: 3.11 가상환경
  • 설치 방식: uv venv + uv pip install 'markitdown[pdf,pptx,docx]'
  • MarkItDown 버전: 0.1.5
  • 테스트 파일 1: gemini-for-google-workspace-prompting-guide-101.pdf
  • 테스트 파일 2: EPC 표준 아키텍처.pptx

실행 커맨드는 이랬다.

uv venv .tmp/markitdown-test/.venv
uv pip install --python .tmp/markitdown-test/.venv/bin/python 'markitdown[pdf,pptx,docx]'

.tmp/markitdown-test/.venv/bin/markitdown "files/gemini-for-google-workspace-prompting-guide-101.pdf" > .tmp/markitdown-test/gemini.md
.tmp/markitdown-test/.venv/bin/markitdown "files/EPC 표준 아키텍처.pptx" > .tmp/markitdown-test/epc.md

시간은 이 정도였다.

입력 걸린 시간 출력 줄 수 첫 인상
PDF 14.76초 1,988줄 본문은 잘 오는데 페이지 번호와 줄바꿈 노이즈가 눈에 띔
PPTX 12.90초 1,964줄 슬라이드 순서는 잘 남지만 시각 레이아웃은 납작해짐

첫 테스트에서 좋았던 점은 둘 다 “아예 못 읽는 수준”은 아니었다는 거다.

PDF는 표지 텍스트, 문단 본문, 리스트, 목차 일부가 꽤 잘 살아남았다.

PPTX는 각 슬라이드가 <!-- Slide number: N --> 주석으로 구분돼서, 슬라이드 단위 후처리에는 오히려 편했다.

하지만 바로 보인 문제도 있었다.

PDF 쪽은 페이지 번호와 폼피드 흔적이 섞여 들어오고, 줄바꿈이 사람이 읽기엔 조금 지저분했다.

PPTX 쪽은 위치 기반 정보가 거의 평평해져서, “왼쪽 박스 vs 오른쪽 박스” 같은 구조는 실질적으로 사라진다.

즉, 텍스트 추출 도구로는 쓸 만하지만, 레이아웃 재현 도구로 착각하면 금방 서운해진다.

실제 출력에서 바로 보였던 장점

좋았던 점은 생각보다 명확했다.

첫째, 입력 타입이 달라도 결과를 한 포맷으로 맞춰준다.

PDF, PPTX, DOCX, HTML, CSV, JSON 같은 게 섞여 있어도 최종 출력이 markdown이면 후속 파이프라인이 단순해진다.

둘째, LLM 입력 전처리용으로는 굳이 예쁘지 않아도 된다.

실무에선 종종 “원문이 100점짜리로 복원되느냐”보다 “에이전트가 일단 읽고 요약할 수 있느냐” 가 더 중요하다.

셋째, CLI가 단순해서 기존 배치 작업에 꽂기 쉽다.

셸 스크립트든, cron이든, MCP wrapper든, 한 단계 넣기가 어렵지 않다.

넷째, 선택 의존성 구조로 바뀌면서 필요한 포맷만 골라 깔 수 있다.

README 기준으로 이전 버전과 달리 [all] 말고도 [pdf], [docx], [pptx], [youtube-transcription] 같이 나눠져 있다.

이건 팀 환경에서 꽤 중요하다.

모든 걸 다 깔면 편하지만, CI나 서버 이미지가 쓸데없이 무거워질 수 있기 때문이다.

바로 걸리는 한계도 분명했다

좋다고만 하면 이 글은 README 다시 써주는 역할밖에 못 한다.

직접 돌려보니 한계도 꽤 선명했다.

첫째, 페이지 노이즈가 남는다.

PDF 출력 초반만 봐도 페이지 숫자와 폼피드 성격의 흔적이 들어간다.

이건 인간이 읽을 땐 거슬리지만, LLM 전처리에선 감당 가능한 수준일 수 있다.

다만 후처리 없이 그대로 검색 인덱스에 넣으면 품질이 약간 흐려질 수 있다.

둘째, PPTX 레이아웃은 포기해야 한다.

슬라이드 번호가 구분돼서 장면 단위 분리는 쉬웠다.

대신 도형 배치, 시각적 강조, 2열 구성, 화살표 흐름 같은 건 거의 텍스트 열로 펴진다.

발표 자료에서 진짜 중요한 게 “문장이 아니라 배치”인 경우가 많다는 걸 생각하면, 이건 꽤 큰 차이다.

셋째, 표와 복잡한 문서에서 항상 깔끔하지는 않다.

README도 사람용 고정밀 변환보다는 텍스트 분석용이라고 분명히 적고 있다.

그 말을 그냥 겸손한 마케팅처럼 읽으면 안 된다.

정말로 사람이 다시 읽을 문서를 만들 때와, 모델에게 맥락을 먹일 때는 평가 기준이 다르다.

넷째, 플러그인과 OCR은 기본값이 아니라 추가 선택이다.

이 말은 곧 “설치하고 바로 끝”이 아니라, 문서 종류에 따라 조금씩 운영 설계를 해야 한다는 뜻이기도 하다.

README에서 지금 꼭 봐야 할 포인트

2026-04-14 기준 README를 다시 읽어보면 중요한 문장이 몇 개 있다.

하나는 MarkItDown이 LLMs and related text analysis pipelines 용이라는 점이다.

다른 하나는 may not be the best option for high-fidelity document conversions for human consumption 이라고 못 박는 부분이다.

쉽게 말하면 이거다.

  • 문서 복원기라기보다 전처리기다
  • 보기 좋은 산출물보다 읽기 좋은 산출물이 목표다
  • 사람 검토용 결과와 모델 입력용 결과를 같은 기준으로 보면 안 된다

지원 포맷도 생각보다 넓다.

  • PDF
  • PowerPoint
  • Word
  • Excel
  • Images
  • Audio
  • HTML
  • CSV/JSON/XML
  • ZIP
  • YouTube URL
  • EPUB

이 넓은 입력 지원이 주는 진짜 이점은 정확도 하나가 아니라 파이프라인 표준화다.

파일 타입마다 변환기를 따로 다는 대신, “일단 markdown으로 모은다”는 규칙을 세울 수 있다.

설치할 때 제일 먼저 정해야 할 것

설치 전에 물어야 할 질문은 생각보다 단순하다.

내가 정말 모든 포맷을 다 다룰 건가 아니면 PDF/PPTX 정도만 먼저 붙일 건가 다.

README 기준 설치 예시는 이렇게 갈린다.

pip install 'markitdown[all]'
pip install 'markitdown[pdf, docx, pptx]'

초기엔 두 번째처럼 좁게 가는 편이 낫다.

이유는 세 가지다.

  • 의존성 충돌 가능성을 줄인다
  • 서버 이미지나 배포 환경을 가볍게 유지한다
  • 실제 사용하는 입력 포맷을 먼저 파악하게 된다

그리고 팀에서 에이전트 도구로 붙일 거라면 개발자 노트북 설치와 운영 환경 설치를 처음부터 나눠서 생각하는 게 좋다.

CLI로 붙일 때 좋은 점

CLI는 정말 단순하다.

markitdown input.pdf > output.md
markitdown input.pdf -o output.md
cat input.pdf | markitdown

이 단순함 덕분에 다른 자동화랑 연결할 때 머리가 덜 아프다.

예를 들면 이런 흐름이 가능하다.

  1. 파일 감지
  2. MarkItDown 변환
  3. 노이즈 라인 정리
  4. 청킹
  5. 임베딩 또는 요약
  6. Obsidian 저장

이때 좋은 점은 문서 파서가 실패했을 때 실패 지점도 비교적 단순하다는 거다.

복잡한 SaaS 변환 API보다 운영 추적이 쉽다.

반대로 귀찮은 점도 있다.

  • OCR은 기본이 아니다
  • 포맷별 품질 편차가 있다
  • 후처리 없는 “완성본”을 기대하면 아쉽다
  • 대량 처리에서는 실패 로그와 재시도 규칙을 따로 가져가야 한다

MCP 서버가 붙었다는 건 왜 의미가 있나

README 상단에는 MarkItDown이 이제 MCP 서버도 제공한다고 적혀 있다.

이 포인트는 그냥 기능 추가 소식 정도로 보면 좀 아깝다.

문서 변환이 이제 “사람이 커맨드 한 번 치는 도구”를 넘어서, 에이전트가 호출할 수 있는 도구 레이어로 들어오기 시작했다는 뜻이기 때문이다.

다만 여기서도 과장하면 안 된다.

MCP 서버가 있다고 해서 자동으로 운영이 좋아지는 건 아니다.

문서 변환은 실패했을 때 왜 실패했는지, 어느 파일에서 깨졌는지, OCR이 필요한지, 출력 정리가 필요한지까지 후속 판단이 따라와야 한다.

그래서 내 기준은 이렇다.

  • 단발성 변환이면 CLI 먼저
  • 팀 공용 워크플로면 MCP 검토
  • 권한, 로깅, 재시도 규칙이 없으면 MCP라도 보류

이 판단축은 Claude Code MCP vs script 2026 — 내부 도구 연결할 때 언제 커스텀 툴이 과하고 언제 셸이면 충분할까 에서 썼던 원칙이랑 거의 같다.

내가 지금 도입한다면 이렇게 자른다

처음부터 거창하게 가지 않을 거다.

1단계는 PDF와 PPTX만 넣는다.

2단계는 변환 후 후처리를 붙인다.

예를 들면 이런 식이다.

  • 연속된 페이지 번호 제거
  • 너무 짧은 단독 라인 병합
  • 슬라이드 번호 주석 유지 여부 선택
  • 문서 타입별 청킹 규칙 분기

3단계에서야 OCR이나 플러그인을 본다.

왜냐면 대부분의 팀은 OCR이 없어서 죽는 게 아니라, 기본 변환 결과도 아직 운영 흐름에 못 녹여서 멈추기 때문이다.

4단계에서 MCP 서버를 붙인다.

그때는 최소한 다음 질문에 답할 수 있어야 한다.

  • 실패한 파일은 어디에 남기는가
  • 성공한 markdown은 어디에 저장하는가
  • 동일 파일 재변환은 어떻게 막는가
  • OCR 비용이나 추가 모델 호출은 누가 통제하는가

이게 없으면 도구가 늘어난 게 아니라 디버깅 지점만 늘어난다.

흔한 오해 세 가지

1. markdown이니까 무조건 깨끗할 거라는 오해

아니다.

markdown은 출력 포맷이 단순한 거지, 입력 품질이 자동으로 정제된다는 뜻은 아니다.

PDF 원문에 페이지 조각과 줄바꿈 노이즈가 많으면 그 흔적이 그대로 온다.

2. 지원 포맷이 많으니 품질도 다 비슷할 거라는 오해

아니다.

지원 여부와 운영 만족도는 다른 이야기다.

문서 타입마다 좋은 지점과 무너지는 지점이 다르다.

PDF, PPTX, 이미지, 오디오를 같은 기대치로 보면 안 된다.

3. MCP가 붙었으니 무조건 에이전트 친화적이라는 오해

반은 맞고 반은 아니다.

도구 호출은 쉬워질 수 있다.

하지만 운영 친화성은 권한 모델, 로그, 재시도, 출력 저장 위치, 후처리 규칙이 정한다.

언제 이 선택이 맞고 언제 아닌가

이 선택이 맞는 경우부터 보자.

  • 문서 원문을 지식 파이프라인에 흘려보내고 싶다
  • 문서마다 다른 파서를 따로 운영하고 싶지 않다
  • 결과가 100점짜리 문서가 아니라도 된다
  • 인간 검토 전 요약, 검색, 인덱싱이 핵심이다
  • markdown 중심 시스템을 이미 갖고 있다

반대로 이럴 땐 신중해야 한다.

  • 결과물을 그대로 고객에게 보여줄 문서로 쓸 생각이다
  • 표, 도표, 다단 레이아웃이 핵심 정보다
  • 법무, 재무, 계약처럼 문자 하나가 민감하다
  • OCR 정확도가 핵심인데 아직 검증이 없다
  • 네트워크 호출, 추가 플러그인, 운영 비용까지 계산해야 한다

한 줄로 줄이면 이거다.

읽히게 만들고 싶으면 MarkItDown

보이게 복원하고 싶으면 다른 도구까지 같이 봐라

실수 TOP

실수 1. 첫날부터 all 옵션으로 다 깐다

편하긴 하다.

근데 대부분의 팀은 정작 PDF와 PPTX만 쓴다.

처음부터 다 깔면 문제 생겼을 때 어디서 꼬였는지 보기도 어렵다.

실수 2. 출력 파일을 사람이 직접 읽을 문서로 본다

그러면 실망이 빨라진다.

MarkItDown은 사람 친화보다 LLM 친화에 가깝다.

실수 3. 변환 뒤 정리 단계를 빼먹는다

페이지 번호, 너무 잘게 쪼개진 줄, 슬라이드 주석 같은 건 가볍게라도 정리해주는 편이 낫다.

실수 4. MCP 서버를 먼저 붙인다

CLI에서 한번도 품질 확인 안 했는데 곧바로 에이전트 도구화하면 실패 원인이 변환인지, 도구 호출인지, 후처리인지 구분이 안 된다.

FAQ

MarkItDown은 PDF 전용 도구야?

아니다.

README 기준으로 PDF, PowerPoint, Word, Excel, 이미지, 오디오, HTML, CSV/JSON/XML, ZIP, YouTube URL, EPUB 등을 지원한다.

다만 지원 포맷이 넓다는 것과 내 워크플로 만족도가 높다는 건 다른 문제라서, 자주 다루는 포맷부터 따로 테스트하는 게 맞다.

MarkItDown 결과를 바로 RAG에 넣어도 될까?

작은 실험이나 내부 검색엔 가능하다.

다만 실제 서비스 인덱스라면 페이지 번호 제거, 헤더/푸터 정리, 청킹 규칙 보정 정도는 같이 붙이는 편이 낫다.

OCR도 바로 되나?

기본값으로 모든 OCR이 자동 해결된다고 보면 안 된다.

README에는 플러그인 방식의 markitdown-ocr와 Azure Document Intelligence 옵션이 같이 나온다.

즉, 이미지 기반 문서가 많다면 추가 설정을 전제로 보는 게 맞다.

MarkItDown이 사람 읽기 좋은 markdown도 만들어 주나?

어느 정도는 된다.

하지만 도구 목표 자체가 고정밀 시각 복원보다 구조화된 텍스트 추출에 가깝다.

사람이 배포용으로 읽을 결과라면 후편집이 거의 항상 필요하다.

MCP 서버가 있으면 바로 붙여도 돼?

단발성 작업이면 CLI부터 권한다.

반복 작업이고, 권한/로그/저장 위치/재시도 규칙까지 설계돼 있을 때 그다음에 MCP를 보는 편이 낫다.

MarkItDown과 OCR SaaS를 어떻게 나눠서 봐야 해?

내 기준은 텍스트 구조화가 주목적이면 MarkItDown, 복잡한 시각 문서를 고정밀로 복원해야 하면 전문 OCR 또는 문서 인텔리전스 계열을 같이 본다.

HTML이나 CSV에도 굳이 markdown이 필요할까?

필요할 때가 있다.

입력 포맷을 하나로 통일하면 후속 요약, 검색, 청킹, 에이전트 컨텍스트 주입이 단순해진다.

그 단순화 자체가 운영 비용을 줄인다.

참고 자료

관련 글