'마크다운도 정식 식구로 인정' PyMuPDF 1.28 주요 업데이트: 샘플 코드 포함

PDF 라이브러리로 익숙한 PyMuPDF가 1.28 버전에서 꽤나 묵직한 업데이트를 들고 나왔습니다. 그동안 쌓아온 개선 사항들을 한 번에 정리해서 내놓은 느낌인데, 문서 처리 쪽 기능이 눈에 띄게 넓어졌습니다.

이번 릴리즈에서 가장 핵심은 두 가지입니다. 마크다운 파일을 PDF, 전자책처럼 완전한 문서 포맷으로 취급하기 시작했다는 점, 그리고 Office 문서를 곧바로 마크다운으로 뽑아낼 수 있게 됐다는 점입니다. 

별거 아닌 것처럼 보일 수 있지만, 마크다운에서 PDF를 만드는 작업부터 문서 분석 파이프라인까지, 뒷단에서 쓰는 여러 도구들이 이 두 기능 덕분에 새로운 방식으로 굴러갈 수 있게 됐습니다.

 

마크다운, 드디어 "정식 식구"가 되다

지금까지는 PyMuPDF에서 마크다운을 다루려면 이런저런 우회가 필요했습니다. 이제는 다릅니다. .md 파일을 네이티브로 열고, 파싱하고, 렌더링하고, 변환할 수 있습니다. PDF나 전자책과 똑같은 위치에 마크다운이 들어왔다고 보면 됩니다.

달라진 점

• .md 파일을 바로 열 수 있습니다
• 레이아웃, 폰트, 이미지, 스타일까지 렌더링 파이프라인이 통째로 지원됩니다.
• 텍스트를 검색하고 선택할 수 있습니다 (이미지로 뭉개지지 않는다는 뜻이죠)
• 하이퍼링크, 이미지, 리스트, 표까지 다 처리됩니다.
• 고품질의 일관된 레이아웃으로 PDF 변환이 가능합니다.

이게 왜 중요할까?

마크다운은 이미 개발자, 테크니컬 라이터, 문서화 툴에서 사실상 표준 작성 포맷입니다. 이걸 네이티브로 지원한다는 건 외부 변환기를 따로 안 써도 되고, HTML을 중간에 끼워 넣지 않아도 되고, 구조가 깨질 걱정도 없다는 뜻입니다. 결과물도 항상 예측 가능하고, 퀄리티가 안정적으로 나옵니다.

한마디로 PyMuPDF는 이제 전통적인 문서 포맷과 요즘 많이 쓰는 텍스트 기반 포맷을 한 번에 다루는 범용 엔진이 됐다고 볼 수 있습니다!

 

CSS로 디자인까지 손보는 마크다운 → PDF 변환

기존에 쓰던 Document.save() 메서드가 이 새 마크다운 엔진을 그대로 품게 되면서, 이제 CSS로 PDF 디자인을 세밀하게 컨트롤하면서 마크다운으로 PDF를 뽑아낼 수 있습니다.

편집 가능 요소는 아래와 같습니다.

• 폰트 (직접 준비한 폰트도 사용 가능)
• 폰트 크기, 자간, 여백
• 색상
• 표 스타일
• 코드 블록 스타일
• 이미지 삽입
• 페이지 레이아웃과 타이포그래피

덕분에 PyMuPDF가 결과물을 예쁘게 뽑아주는, 스크립트로 다룰 수 있는 가벼운 PDF 생성기 역할까지 하게 됐습니다.

 

일단 제일 간단한 예시부터 살펴볼까요?

example.md라는 마크다운 파일이 있다고 해봅시다.

# Title

## A Table

|**Boiling Points °C**|**min**|**max**|**avg**|
|---|---|---|---|
|**Noble gases**|-269|-62|-170.5|
|**Nonmetals**|-253|4827|414.1|
|**Metalloids**|335|3900|741.5|
|**Metals**|357|>5000|2755.9|

## A List

* Comment 1
* Comment 2
* Comment 3 with a link to [Find out more](https://pymupdf.readthedocs.io)

## My TO-DOs

* [x] Done!
* [x] Also done!
* [ ] Still open

이걸 PDF로 만드는 코드는 정말 이게 다입니다.

import pymupdf
md_doc = pymupdf.open("example.md") # open the MD text file
md_doc.save("example.pdf")

파이썬 코드 두 줄 만에 마크다운 파일이 깔끔하게 스타일링된 PDF 한 장으로 바뀝니다.

 

여기에 CSS까지 얹는다면?

마크다운 원본은 하나도 안 건드리고, CSS만 살짝 얹어서 폰트를 지정하고 텍스트를 꾸며볼 수 있습니다. 아래 파이썬 코드를 보시죠.

import pymupdf

css = """
@font-face {
    font-family: 'FreightSans Bold';
    src: url(FreigSanProBol.ttf);
}

h1 {
    font-size:50px;
    font-family: 'FreightSans Bold';
    border:2px solid #ff00ff;
    background: yellow;
    text-align:center;
}

table {
    width: 100%;
}

ul li {
    color: green;
}
"""

# 폰트가 들어있는 폴더를 가리키는 Archive 생성
archive = pymupdf.Archive("fonts")  # 폰트가 여기 있음
archive.add(".")  # 이미지는 이 스크립트와 같은 폴더에 저장해둠

md_file = "test.md"
md_doc = pymupdf.open(  # 마크다운 문서 열기
    md_file,
    archive=archive,  # 리소스(폰트, 이미지)를 찾을 위치
    rect=pymupdf.paper_rect("A4"),  # 페이지 크기: ISO A4
)

md_doc.apply_css(css)  # CSS 적용

md_doc.save("example.pdf") # PDF로 저장

코드를 보면 "FreightSans Bold"라는 폰트를 참조하는 CSS 문자열을 하나 만들었습니다. 이 폰트가 "fonts" 폴더 안에 들어있다고 치고, 그 폴더를 가리키는 archive를 만들어서 Document 인스턴스에 넘겨줍니다. 그다음 CSS를 적용하고 PDF로 저장하면 끝입니다.

이 CSS가 하는 일은 간단합니다. H1 제목에 테두리와 배경색을 넣어 꾸미고, 표는 페이지 폭에 맞춰 늘리고, 리스트 항목은 초록색 글씨로 바꿔줍니다. 아래처럼요. 

 

커스텀 태그로 이미지까지 마음대로

여기서 한 걸음 더 나가서, 마크다운 안에 커스텀 태그를 넣고 CSS로 그 태그를 직접 겨냥해서 스타일을 줄 수도 있습니다. 예를 들어 마크다운에 이런 걸 추가했다고 해봅시다.

<mytag>Hello World</mytag>

그러면 CSS에서 이렇게 바로 잡아낼 수 있습니다.

mytag { ... }

이 방식을 응용하면 이미지 배치와 크기 조절도 쉬워집니다. 앞서 만든 표 아래에 마크다운으로 이렇게 추가하고,

<mytag><img src="pie-chart.png" /></mytag>

"pie-chart.png"가 같은 폴더(또는 archive)에 있다면, CSS에서 크기를 이렇게 딱 정해줄 수 있습니다.

mytag img {
    width:100px;
    height:100px;
}

이렇게 해두면 이미지 원본 크기가 얼마든 상관없이 원하는 크기로 딱 맞춰 넣을 수 있습니다. 이 설정을 안 해주면 이미지는 원래 크기 그대로 들어갑니다.

CSS를 적용하고 마크다운에 커스텀 태그까지 넣으면, 최종적으로 이런 결과물이 나옵니다.

 

Office 문서도 마크다운으로

PyMuPDF에서 추가 기능이 포함된 상용버전,  PyMuPDF Pro 1.28의 또 다른 핵심 업데이트는 Office 문서를 마크다운으로 변환하는 기능입니다. office_to_markdown() 메서드 하나면 어떤 Office 문서든 마크다운 형태로 뽑아낼 수 있습니다.

코드는 정말 딱 한 줄입니다.

md = pymupdf.pro.office_to_markdown("my-office-doc.xls")

바이너리 포맷으로 저장된 Office 문서는 사실 열어보기 전까진 블랙박스나 다름없죠. 마크다운으로 변환하면 그 껍데기를 벗겨내고 콘텐츠 알맹이만 그대로 손에 넣을 수 있습니다.

이게 왜 중요할까요?

• 어디서든 열립니다. 텍스트 에디터든 터미널이든 AI 모델이든, 별도 프로그램 없이도 바로 읽힙니다. 렌더링이 깨질 일도 없고요.
• 용량이 확 줄고 빨라집니다. 두꺼운 워드 문서도 몇 KB짜리 텍스트로 압축됩니다. 저장하고, 동기화하고, 검색하기가 훨씬 편해지죠.
• 버전 관리가 됩니다. Git이 "바이너리 파일 수정됨"이라고 뭉뚱그려 말하는 대신, 실제로 어느 줄이 바뀌었는지 보여줍니다.
• AI와 궁합이 좋습니다. LLM은 마크다운을 물 흐르듯 읽고 씁니다. 이미 여러분이 쓰는 AI 도구들의 언어이기도 하고요.
• 어디든 옮겨 붙일 수 있습니다. 위키든, 정적 사이트든, README든, 채팅창이든 상관없습니다.
• 특정 회사나 프로그램에 발목 잡히지 않습니다. 라이선스나 앱 버전, 독점 포맷 때문에 콘텐츠가 묶일 일이 없습니다.

정리하면, PyMuPDF Pro의 이번 업데이트로 Office 파일을 마크다운으로 손쉽게 바꿀 수 있게 되면서, 콘텐츠를 뒷단 파이프라인 어디에든 자유롭게 흘려보낼 수 있게 된 겁니다.

마무리

PyMuPDF 1.28은 오랜 시간 준비해온, AI 시대에 맞춰 나온 무게감 있는 업데이트입니다. 마크다운은 이미 LLM과 RAG 파이프라인이 쓰는 기본 언어인데, PyMuPDF는 이제 이걸 양방향으로 능숙하게 다룹니다. 마크다운을 정식 포맷으로 받아들이는 동시에, 모델에 바로 넣을 수 있을 만큼 깔끔하고 구조화된 마크다운을 뽑아내는 것까지요. 여기에 CSS로 컨트롤하는 PDF 생성 기능까지 더해지면서, 이번 릴리즈로 PyMuPDF는 AI 기반 애플리케이션을 만드는 데 있어 손꼽히는 문서 툴킷 중 하나가 됐습니다!

---

🎉 Happy Coding! 🙂

PyMuPDF에 대해 더 궁금하시다면, 이파피루스 홈페이지를 방문해주세요!

👉 문서 데이터 추출 파이썬 라이브러리 PyMuPDF Pro