Markdown에서 PDF로, 다시 돌아오기: 형식 변환이 지키는 것

Markdown과 PDF는 서로 다른 계약에 맞춰져 있습니다. Markdown은 버전 관리에 잘 맞는 구조이고, PDF는 고정된 페이지 기술입니다. 한쪽으로 변환했다가 되돌리는 일은 쓸모가 있지만, 무손실 보관 순환은 아닙니다.

Markdown에서 PDF로: 구조가 페이지가 됩니다

Markdown을 PDF로(POST /api/v1/convert/markdown/pdf)는 .md 파일이나 Markdown을 담은 ZIP을 받습니다. Markdown도 ZIP도 아닌 업로드는 거부됩니다. 순수 .md 입력에는 UTF-8이 필요합니다. 파이프라인은 Markdown을 표, 취소선, 작업 목록이 켜진 HTML로 렌더링하고, 그 HTML을 인쇄 지향 CSS(여러 문자 체계를 위한 글꼴 스택과 아랍어가 감지되면 RTL 포함)로 감싼 뒤 WeasyPrint로 PDF로 인쇄합니다.

정방향 변환에서 대체로 살아남는 것:

• 제목, 문단, 목록, 단순한 Markdown 표
• HTML 경로가 배치할 수 있는 여러 문자 체계 텍스트(인쇄 CSS가 덮는 CJK와 라틴 문자 등)
• 문서를 코드로 다루는 워크플로를 위한 인쇄 가능하고 공유 가능한 PDF

살아남지 않는 것:

• 편집기 테마 글꼴이 모든 뷰어에서 보장된 모습으로 나오는 것
• .md 파일의 정확한 화면 줄바꿈
• PDF에 대응물이 없는 대화형 Markdown 기능(실시간 체크박스, 접이식 구역, 위키 링크)

ZIP 입력은 HTML 경로가 문서 옆에서 찾을 수 있는 자산과 Markdown을 함께 묶기 위한 것입니다. 포장상의 편의로 보고, 모든 상대 경로 이미지나 CSS 참조가 모든 뷰어에서 똑같이 보인다는 보장으로 보지는 마세요.

PDF에서 Markdown으로: 텍스트 레이어는 들어가고 Markdown이 나옵니다

PDF를 Markdown으로(POST /api/v1/convert/pdf/markdown)은 pdf-inspector로 텍스트 내용을 Markdown으로 추출합니다. 응답은 text/markdown이고 .md 파일로 내려받습니다. 텍스트 레이어가 깨끗한 전자 문서 PDF가 가장 잘 변환됩니다. 텍스트 레이어가 없는 스캔 페이지는 먼저 OCR하지 않으면 비어 있거나 쓸모없는 Markdown을 낳습니다. 이 사이트의 OCR도 검색 가능한 PDF 레이어가 아니라 Markdown을 반환합니다.

예상할 수 있는 것:

• 글자 크기 휴리스틱이 제대로 맞을 때의 제목과 문단(# 단계는 손으로 다시 매겨야 할 수 있습니다)
• 인식이 되면 Markdown 표가 되고, 다단 레이아웃은 다른 읽기 순서로 펼쳐질 수 있습니다
• 페이지마다 반복되는 머리말과 꼬리말(나중에 직접 정리)
• 이미지와 그림 형태의 수식이 자동으로 로컬 자산이나 LaTeX가 되지는 않습니다

제목 휴리스틱 없이 평범한 산문이 필요하면 PDF를 텍스트로가 더 평평한 추출입니다. 표 형태 내보내기가 HTTP 204를 반환하면 열 블록을 찾지 못한 것입니다. 빈 표 내보내기(204)를 보세요.

왕복이 실제로 증명하는 것

두 번 왕복하면 어긋납니다. Markdown→PDF는 WeasyPrint를 거쳐 다시 흐르고, PDF→Markdown은 추출 휴리스틱으로 구조를 다시 세웁니다. 어느 단계도 상대 형식의 레이아웃 모델을 무손실 중간물로 저장하지 않습니다.

기준 방향을 하나 고르세요

인쇄 레이아웃이 시스템의 기준이어야 한다면 PDF를 보관하고 Markdown은 내보내기나 에이전트 입력으로 다루세요. diff와 코드 리뷰, 에이전트 입력이 필요하다면 Markdown을 우선하고 PDF를 발행 단계로 다루세요. 둘 다 똑같은 “사실의 원천”으로 저장해 두고 편집 후에도 동일하게 유지되기를 기대하지는 마세요.

실용적인 문서-코드 순환은 이렇습니다. Git에서 Markdown을 편집하고 → 공유할 결과물은 Markdown을 PDF로 변환해 만들고 → PDF→Markdown→PDF를 일상 습관으로 삼지 않습니다. 전자 문서 PDF를 넘겨받아 에이전트에 넣을 텍스트가 필요할 때만 PDF→Markdown을 쓰고, 그 Markdown은 새 초안으로 다루지 원본 쪽 나눔의 보장으로 다루지 않습니다.

암호화된 파일은 어느 변환이든 하기 전에 권한 있는 비밀번호 해제가 필요합니다. 파싱되지 않는 손상 파일은 먼저 문서 정보 / PDF 복구를 거쳐야 합니다. 같은 엔드포인트를 HTTP로 쓰려면 개발자를 보세요.