MarkItDown으로 PDF를 Markdown으로 옮길 때 확인할 것 — Toolbox

공식 문서 기반 안내 · 2026년 10월 2일 확인 · 설치와 변환 품질은 직접 시험하지 않았다.

PDF 보고서, Word 회의록, Excel 집계표를 함께 검색하려면 먼저 각 파일에서 읽을 내용을 꺼내야 한다. Microsoft의 MarkItDown은 여러 파일 형식을 Markdown으로 변환하는 Python 도구다. 제목·목록·표·링크 같은 구조를 남겨 LLM이나 텍스트 분석에 쓰도록 만든다. 원본과 똑같은 화면을 재현하는 용도로는 적합하지 않을 수 있다고 개발팀도 설명한다. Microsoft 공식 저장소

이 도구를 검토할 이유는 서로 다른 문서를 같은 텍스트 형식으로 다룰 수 있다는 데 있다. 다만 파일 확장자가 .md로 바뀌었다고 AI에게 넘길 준비까지 끝난 것은 아니다. 보고서의 본문과 표가 어떤 순서로 옮겨졌는지, 중요한 숫자가 빠지지는 않았는지 확인하는 단계가 남는다.

비신뢰 입력을 다룰 때는 실행 권한부터 확인한다

Microsoft의 보안 안내에 따르면 MarkItDown은 실행 중인 프로세스의 권한으로 파일과 네트워크 자원에 접근한다. 신뢰할 수 없는 파일 경로나 URL을 검증 없이 넘겨서는 안 된다. 특히 외부 사용자가 입력을 정하는 자동 변환 서비스라면 허용할 파일 경로, URI 방식과 접속 대상을 제한해야 한다. 환경에 따라 내부망·루프백·링크 로컬·메타데이터 서비스 주소로의 접근을 막는 조치도 필요하다. Microsoft 공식 보안 안내

이 경고를 첫 시험에 적용한다면 출처를 확인한 샘플 사본만 사용하고, 변환에 필요하지 않은 파일이나 네트워크에 접근할 권한은 주지 않는 방식으로 실행 환경을 정해야 한다. 관리자 권한을 불필요하게 부여하지 않는다. 별도 작업 폴더를 만들었다는 사실만으로 프로세스의 접근 권한까지 제한됐다고 판단해서도 안 된다.

Python 코드에 넣을 때는 필요한 범위의 API를 고른다. 공식 문서는 로컬 파일만 읽을 경우 convert_local()을, 입력 스트림을 직접 관리하려면 convert_stream()을 제시한다. 범용 convert()가 로컬 파일뿐 아니라 원격 URI도 받을 수 있다는 점을 고려한 선택이다. API 선택과 입력 검증은 함께 적용해야 한다.

우선 PDF 한 개를 변환한다면

공식 README는 PDF 외에도 Word, Excel, PowerPoint, 이미지, 오디오, HTML, CSV 등을 지원 대상으로 적고 있다. 형식별 의존성을 골라 설치할 수 있으며, 현재 안내하는 Python 범위는 3.10~3.14다. 설치와 선택 의존성

아래는 PDF 변환을 확인하기 위한 명령 예시다. 입력 파일명은 report.pdf, 출력 파일명은 report.md로 정했다. 이 글에서 실행한 기록은 아니다. Python 가상환경을 준비한 뒤, 기존 파일이 없는 별도 작업 폴더에서 사용할 수 있다.

python -m pip install 'markitdown[pdf]'
markitdown report.pdf -o report.md

변환기가 추출한 내용은 report.md에 담긴다. 여기서 바로 여러 문서를 일괄 처리하기보다 원본과 변환본을 나란히 열고 한 개의 결과부터 살펴보는 편이 검수 범위를 정하기 쉽다. 명령의 사용법은 공식 CLI 안내에 있다.

출력 파일에서 먼저 볼 곳

다음은 변환 성능에 대한 평가 결과가 아니라, 보고서나 업무 자료에 적용할 때 쓸 수 있는 검수 항목이다.

제목과 본문 순서: 두 단으로 편집된 본문, 머리말, 꼬리말이 본문 사이에 끼어들지 않았는지 본다. 목차만 읽힌 것을 본문까지 읽힌 것으로 판단하지 않는다.
표의 숫자와 단위: 행·열 제목이 값과 맞게 연결됐는지 원본과 대조한다. 예를 들어 면적 열의 m²가 빠지거나 합계가 다른 항목에 붙으면, 이후 요약이 자연스러워도 근거로 쓰기 어렵다.
주석과 출처: 각주 번호와 설명, 표 하단의 단서가 함께 남았는지 확인한다. 기준 연도나 제외 조건이 빠지면 같은 숫자도 뜻이 달라진다.
그림 안의 정보: 지도 범례, 도면 치수, 그래프의 축이 필요한 자료라면 해당 부분을 따로 확인한다. Markdown 본문에 문장이 많다는 이유로 그림까지 읽혔다고 볼 수는 없다.

가령 조사 보고서에서 사업명과 면적을 찾는 용도라면, 먼저 정답을 알고 있는 항목 몇 개를 골라 원문 위치와 함께 적어 둔다. 변환본에서 그 항목을 다시 찾아 값과 단위를 대조한다. 이 단계에서 빠진 정보는 검색용 데이터에 넣기 전에 보완하거나 제외해야 한다.

스캔 문서는 OCR 경로를 따로 본다

PDF 지원 여부만으로 스캔 문서의 글자 인식 품질까지 판단할 수는 없다. 공식 저장소의 markitdown-ocr 플러그인은 PDF·Word·PowerPoint·Excel에 들어 있는 이미지를 비전 모델로 읽는 경로를 제공한다. 플러그인을 켜는 것에 더해 LLM 클라이언트와 모델을 설정해야 하며, 클라이언트가 없으면 OCR을 건너뛴다고 명시한다. OCR 플러그인 문서

따라서 스캔 보고서를 다루려면 텍스트가 있는 PDF와 시험을 나눠야 한다. 먼저 한 페이지에서 문장이 실제로 추출되는지 보고, 글자가 읽힌 뒤에도 표의 줄바꿈이나 숫자 오인식이 없는지 확인한다. 손글씨와 작은 도면 문자는 별도 시험 대상으로 남겨 두는 것이 맞다.

외부 모델이나 클라우드 문서 분석 서비스를 연결한다면 문서가 전달되는 곳도 확인해야 한다. 계약서, 고객 자료, 비공개 설계 자료로 시작하기보다 공개 자료나 민감한 내용을 지운 사본으로 변환 경로를 먼저 점검할 수 있다.

기존 변환 절차와 연결할 때

MarkItDown은 내용을 추출하는 도구 후보이고, 원본 보존과 출력 검수는 그 바깥의 절차다. 기존 PDF 변환 표준을 적용하는 작업이라면 원본 해시, 별도 출력 위치, 누락·수정 내역과 검증 기록도 그 표준에 맞춰 남겨야 한다. Markdown 파일을 만들었다는 사실만으로 기존 절차를 대체하거나 표준을 충족했다고 판단할 수는 없다. 이 글에서는 MarkItDown과 기존 도구의 동등성 시험이나 채택 결정을 다루지 않는다.

AI에게 넘길 때 원본도 함께 남긴다

Markdown을 검색이나 질의응답에 넣는다면 변환본마다 원본 파일명과 문서 날짜, 다시 찾아갈 수 있는 위치를 별도로 기록해 두는 방법이 있다. 이것은 MarkItDown이 모든 입력에서 자동으로 만들어 준다고 확인한 기능이 아니라, 출처를 잃지 않기 위한 작업 제안이다.

도면의 좌표나 형상을 그대로 보존해야 하는 작업이라면 이 글의 변환 절차만으로 판단하지 않는다. 여기서 제안하는 첫 시험은 공개 보고서 한 개다. 본문과 표를 원본에 대조하고, 빠진 항목과 손으로 고친 항목을 기록하면 다음 파일에도 같은 도구를 쓸지 판단할 근거가 생긴다.