여러 PDF를 한 번에 마크다운으로 변환하기

파일 수에 맞춰 방법 고르기

어떤 방법이 맞는지는 PDF 자체보다 파일이 몇 개인지, 얼마나 자주 하는 작업인지에 달려 있습니다. 대략 이렇습니다.

• 몇 개에서 수십 개, 한 번만: 브라우저 일괄 변환 페이지. 설치할 것도 없고 파일은 내 기기에 남습니다.
• 수백 개, 또는 매주: 폴더를 도는 파이썬 반복문. 예약 실행, 로그 기록, 폴더 구조 유지가 가능합니다.
• 스캔본, 양식, 수식, 특이한 레이아웃: marker 같은 모델 기반 도구. 일반 노트북에서는 훨씬 느립니다. 텍스트 레이어가 없는 페이지를 OCR로 읽도록 만들어졌지만, 저희 CPU 실행에서는 스캔 페이지가 그래도 비어 있었습니다. 먼저 몇 개로 시험해 보세요.

세 방법을 공정하게 비교하려고 파일 20개, 총 40쪽짜리 테스트 세트를 썼습니다. 표·레이아웃 예제 12개, 영문 가이드, 11쪽 중국어 보고서, 머리글이 반복되는 4쪽 보고서, 텍스트 레이어가 없는 스캔 페이지 1개, 그리고 서로 다른 폴더에 있는 같은 이름(notes.pdf)의 다른 파일 2개입니다. 모두 저희 빌드 기기(Linux x86_64, 8 vCPU, 16 GB RAM, no GPU)에서 돌렸습니다.

브라우저에서 여러 PDF를 마크다운으로 변환

시작하기 전에 PDF 두세 개를 열어 문장을 드래그해 보세요. 선택이 되면 텍스트 레이어가 있는 파일이고 아래 방법이 모두 통합니다. 아무것도 선택되지 않으면 스캔본이나 이미지라서 OCR 도구만 글자를 뽑을 수 있습니다. 어떤 파일이 섞여 있는지 미리 알면 두 번 돌릴 일이 줄어듭니다.

일괄 변환 페이지를 열고 파일 선택을 누르거나(또는 놓기 영역에 끌어다 놓고) PDF를 한꺼번에 고르세요. 파일은 탭 안에서 하나씩 변환되고, 페이지는 PDF마다 .md 하나씩 든 ZIP 하나를 내줍니다. 작업이 로컬에서 이뤄지므로 속도는 업로드가 아니라 내 기기 성능에 달려 있습니다. 파일이 모두 한 컴퓨터에 있다면 여러 PDF를 마크다운으로 변환하는 가장 빠른 방법입니다.

테스트에서 파일 선택부터 ZIP 완성까지 전체 세트가 Chrome 155.0.8059.84에서 약 0.8초 걸렸습니다(세 번 실행, 0.8~1.0초). ZIP에는 Markdown 파일 20개가 들어 있었습니다. notes.pdf 두 개는 notes.md와 notes-2.md로 나와 서로 덮어쓰지 않았고, 스캔 페이지는 조용히 실패하는 대신 목록에 표시됐습니다.

한계도 있습니다. 브라우저는 스스로 폴더 트리를 읽지 못해서 여러 폴더의 파일이 ZIP 하나에 나란히 담기고, 아주 많은 양은 탭의 메모리에 막힙니다. 수백 개라면 여러 번에 나눠 고르거나 스크립트로 넘어가세요.

pymupdf4llm로 파이썬 반복문 돌리기

이 작업용 파이썬 스크립트는 몇 줄이면 됩니다. 아래 스크립트는 PDF 폴더를 마크다운으로 바꿉니다. 폴더를 돌면서 출력에도 같은 구조를 유지하고(그래서 notes 파일 두 개가 따로 남습니다), 한 파일이 실패해도 계속 진행합니다.

import pathlib, pymupdf4llm

src, out = pathlib.Path("pdfs"), pathlib.Path("markdown")
for pdf in sorted(src.rglob("*.pdf")):
    dest = out / pdf.relative_to(src).with_suffix(".md")
    dest.parent.mkdir(parents=True, exist_ok=True)
    try:
        dest.write_text(pymupdf4llm.to_markdown(str(pdf)), encoding="utf-8")
    except Exception as e:
        print(f"skipped {pdf}: {e}")

같은 20개 파일로 돌린 반복문은 파이썬 시작과 라이브러리 임포트를 포함해 5.3초 만에 끝났습니다. 파일 20개를 썼고, 그중 두 개가 비어 있었습니다. 읽을 텍스트가 없는 스캔 페이지와 90도 돌아간 표가 있는 페이지입니다. 파일이 수천 개라면 파일마다 독립적이니 같은 반복문을 CPU 코어당 워커 하나씩 프로세스 풀로 돌리면 됩니다. 표와 쪽 범위 옵션은 파이썬 가이드에, pymupdf4llm과 다른 두 라이브러리의 비교는 라이브러리 비교 글에 정리했습니다.

marker 폴더 명령

marker에는 폴더 전체를 처리하는 명령 marker /path/to/pdfs --output_dir out이 있습니다. 폴더의 최상위만 읽기 때문에(스크립트가 os.listdir로 목록을 만듭니다) 먼저 파일을 평평한 폴더 하나에 복사했습니다. 쓸 만한 옵션은 병렬 처리용 --workers, 중단된 실행을 이어 가는 --skip_existing, 시험 실행용 --max_files입니다.

GPU 없는 저희 기기에서 기본 설정으로 돌리자 모델 로딩을 포함해 5분 51초이 걸렸고 결과 20개가 나왔습니다. 파이썬 반복문보다 약 66배 깁니다. 돌아간 표는 살려 냈지만 두 번 썼고, 스캔 페이지는 이번에도 빈 파일이었습니다. 지원되는 GPU가 있는 기기라면 이야기가 다르지만, 노트북에서는 marker가 꼭 필요한 파일에만 쓰세요.

파일 이름, 중복, 폴더 구조

• 중복: PDF를 한꺼번에 많이 변환할 때는 서로 다른 폴더의 같은 이름을 어떻게 처리할지 정하세요. 저희 일괄 변환 페이지는 번호를 붙이고, 위 반복문은 하위 폴더를 유지합니다. 대충 짠 스크립트는 경고 없이 첫 파일을 덮어씁니다.
• 구조: 고객별, 연도별처럼 폴더 트리에 의미가 있다면 위처럼 relative_to를 쓰거나, 폴더마다 일괄 변환 페이지를 한 번씩 써서 구조를 지키세요.
• 이름: .md에는 PDF의 기본 이름을 그대로 두세요. 그래야 원본을 늘 찾을 수 있습니다. 읽기 좋은 이름은 나중에 노트 앱에서 바꾸면 됩니다.
• Markdown 파일 ZIP은 다른 사람에게 넘기기 가장 쉽고, 출력이 다른 스크립트로 들어간다면 폴더가 낫습니다.

품질 점검: 스캔본과 빈 결과 찾기

여러 PDF를 한 번에 마크다운으로 변환하면, 파일 하나였다면 바로 보였을 문제를 놓치기 쉽습니다. 이번 테스트의 모든 도구가 빈 파일이나 거의 빈 파일을 하나 이상 만들었고, 어떤 도구도 OCR 없이 읽을 수 없는 페이지를 글자로 바꾸지는 못합니다. 그러니 크게 돌린 뒤에는 지나치게 짧은 파일을 찾아보세요.

# Markdown files under 100 bytes are usually scans or image-only pages
find markdown -name '*.md' -size -100c

그다음 결과 몇 개를 무작위로 열어 PDF와 비교하세요. 제목, 표 하나, 마지막 문단 정도면 됩니다. 파일을 채팅 모델에 넣을 거라면, ChatGPT에 가장 좋은 문서 형식 글에서 깔끔한 Markdown을 위해 이 점검이 왜 가치 있는지 설명합니다.

20개 파일로 잰 시간

대부분에게 결론은 간단합니다. 여러 PDF를 한 번에 마크다운으로 변환하려면 브라우저에서 시작하고, 반복되면 스크립트로 만들고, 다른 도구가 못 읽는 페이지에만 모델 기반 도구를 쓰세요.