pdf-to-markdown

一個給 Claude 用的 Skill：把 PDF 轉成 Markdown (.md)。可用於 Claude Code、Claude.ai（Chat）與 Cowork。

功能

• 抽取文字，依字級自動推斷標題層級（# / ## / ###）
• 表格轉成 Markdown 表格
• 嵌入圖片存檔，並在 Markdown 以連結引用
• 掃描型 PDF（影像、無文字層）：自動偵測，渲染成高解析 PNG，交由 Claude 的視覺能力辨識補字（中文辨識佳、零安裝、不需 Tesseract）
• 逐頁進度顯示，緩解等待焦慮
• 安全：絕不覆蓋既有檔（同名自動改存 名稱-1.md、-2.md）

環境需求

• Python 3
• PyMuPDF：python -m pip install pymupdf

直接用指令

python scripts/pdf_to_md.py "你的檔案.pdf"

常用選項：

選項	說明
-o 輸出.md	指定輸出路徑（預設與來源 PDF 同目錄、同名）
--dpi 300	提高掃描頁渲染解析度（中文小字時建議）
--no-images	不擷取嵌入圖片
--force-ocr	所有頁都當掃描頁渲染（文字層損壞 / 亂碼時用）
--quiet	不顯示逐頁進度

輸出：<名稱>.md 與圖片資料夾 <名稱>_assets/ 放在來源 PDF 同目錄。

在 Claude 裡使用

• Claude Code / Cowork（本機）：把整個資料夾放到 ~/.claude/skills/pdf-to-markdown/，直接說「幫我把這份 PDF 轉成 markdown」即可觸發。
• Claude.ai（Chat）：把資料夾壓成 zip（根目錄要是 pdf-to-markdown/，路徑用正斜線），到 Settings 開啟 Code execution，再到 Skills 上傳。

詳見 安裝與使用說明.md。

運作方式

確定性的抽取工作由 scripts/pdf_to_md.py（只依賴 PyMuPDF）完成；掃描頁的文字辨識則由具視覺能力的 Claude 在執行時補上——腳本會在 .md 留下 <!-- OCR-PLACEHOLDER --> 佔位，由模型讀圖辨識後填回。

已知限制

• 表格偵測對「有格線」的表格效果最好；無格線的鬆散排版可能被當成一般段落。
• 多欄 / 複雜版面順序可能錯置，可改用 --force-ocr 讓模型整頁視覺辨識。