파일을 마크다운으로 바꾸는 MS 오픈소스 markitdown

오픈소스 트렌딩에 오른 문서 변환 도구

마이크로소프트가 공개한 markitdown이 최근 GitHub 오픈소스 트렌딩에 올랐어요. 오늘 하루 새로 붙은 스타만 771개, 누적 스타는 18만 개가 넘는 파이썬 유틸리티예요. fork가 1만 3천여 개에 달하고 라이선스는 MIT라서 누구나 자유롭게 쓸 수 있어요.

출처: Microsoft MarkItDown GitHub 저장소

이 도구가 하는 일은 딱 하나예요. PDF, 파워포인트, 워드, 엑셀부터 이미지와 오디오, 유튜브 URL까지 다양한 파일을 마크다운 한 가지 형식으로 바꿔주는 거예요.

문서를 LLM이 읽을 형식으로, 왜 마크다운일까

LLM이나 텍스트 분석 파이프라인에 PDF나 PPT를 그대로 넣을 수는 없어요. 미리 텍스트로 뽑아서 넣어야 하는데, 이때 기존 도구들은 평문만 추출하느라 제목·표·링크 같은 문서 구조가 사라져요. markitdown은 문서 구조를 마크다운으로 보존하는 데 초점을 맞춰요.

프로젝트 문서에 따르면 마크다운은 평문에 가까우면서도 최소한의 마크업으로 구조를 표현할 수 있고, GPT-4o 같은 LLM이 방대한 마크다운 텍스트로 학습돼 이를 원어민 수준으로 이해한다고 해요. 게다가 토큰 효율이 높아 분석 비용을 아끼는 데 유리하죠. 다만 사람이 읽기 좋은 고충실도 변환기라기보다 LLM 분석용이라는 점을 명확히 밝혀요.

지원 형식을 표로 정리하면 이래요.

설치는 간단해요, CLI부터 파이썬 API까지

Python 3.10 이상이면 pip 한 줄로 설치돼요.

pip install 'markitdown[all]'

CLI는 파일 경로를 넘기면 마크다운이 출력돼요.

markitdown path-to-file.pdf -o document.md

파이썬 API도 비슷하게 간단해요. 객체를 만들고 convert()를 부르면 result.markdown으로 결과를 받아요.

from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("test.xlsx")
print(result.markdown)

의존성을 아끼고 싶다면 PDF, 워드, 파워포인트만 골라 markitdown[pdf, docx, pptx]처럼 설치할 수도 있어요. Docker 이미지로 돌리는 방법도 제공하고요.

이미지나 파워포인트 안의 그림을 설명하고 싶다면 llm_client와 llm_model을 넘겨 LLM이 캡션을 붙이게 할 수 있어요. 현재 이 기능은 파워포인트와 이미지 파일에만 적용돼요.

품질과 확장은 Azure, 그리고 플러그인

기본 변환기로 부족하면 마이크로소프트의 Azure 옵션을 붙일 수 있어요. Azure Content Understanding은 문서·이미지·오디오·비디오를 아우르는 멀티모달 변환을 지원하고, 분석기가 뽑아낸 구조화 필드(송장의 VendorName·InvoiceDate 같은 값)를 YAML front matter로 함께 내보내요. 비디오 변환은 이 경로가 유일한 선택지예요.

Azure Document Intelligence는 CLI에 -d 플래그 하나만 붙이면 쓸 수 있고, 환경 변수로 엔드포인트를 지정할 수도 있어요. 다만 Azure 경유 변환은 호출 건마다 유료라 cu_file_types로 PDF 같은 일부 형식에만 적용되게 제한할 수 있어요.

확장은 플러그인으로도 가능해요. 기본적으로 비활성이지만 --use-plugins로 켜고, #markitdown-plugin 해시태그로 GitHub에서 찾을 수 있어요.

markitdown-ocr처럼 이미지 속 텍스트를 LLM 비전으로 OCR해주는 플러그인도 공개돼 있구요. 저장소는 GitHub 토픽에 autogen·langchain·openai를 달고 있고 markitdown-mcp 패키지도 공식 관리 범위라 에이전트·MCP 도구와 자연스럽게 엮이는 생태를 노리는 게 보여요.

쓰기 전에 알면 좋아요: 범위와 보안

이 저장소의 목적은 다른 시스템에 포함될 라이브러리를 만드는 것이에요. 웹 API나 GUI 같은 최종 사용자용 앱은 명시적으로 범위 밖이라, 그런 형태가 필요하면 PyPI의 markitdown을 의존성으로 쓰는 별도 프로젝트를 만들길 권장해요.

보안도 신경 쓸 곳이 있어요. 변환 과정은 현재 프로세스가 가진 권한으로 파일과 URL에 접근해요. 서버 환경에서 사용자 입력을 그대로 넘기면 사설망이나 메타데이터 주소로 요청을 보내는 SSRF 문제로 이어질 수 있어요.

로컬 파일만 다룬다면 convert_local()처럼 범위를 좁힌 API를 쓰고 입력을 잘 검증하는 게 좋아요.

정리하면 이래요. PDF·오피스 문서를 LLM 파이프라인의 먹이로 만들어야 한다면, pip 한 줄 설치 후 CLI 하나로 바로 시작할 수 있는 오픈소스예요. 다만 복잡한 문서의 고품질 변환이 필요하면 Azure 옵션과 유료 호출을 염두에 두어야 해요.

참고 링크

• GitHub — microsoft/markitdown
• PyPI — markitdown