使用 pdfpecker 製作與讀取 PDF
pdfpecker 能將 HTML 和 CSS（或 Markdown）轉換為 PDF，無需瀏覽器，並能將 PDF 頁面渲染回圖片，讓您可以檢視製作的結果。請依此順序操作：編寫 HTML、轉換、檢視頁面、修正、再次轉換。
設定
python3 -c "import pdfpecker" 2>/dev/null || python3 -m pip install --quiet pdfpecker
輔助腳本位於此技能資料夾中的 scripts/pdf.py（在 Claude Code 中為：${CLAUDE_SKILL_DIR}/scripts/pdf.py）。
它封裝了套件，讓您無需自行編寫 Python 即可完成常見任務：
python3 scripts/pdf.py html invoice.html invoice.pdf # 圖片和 CSS 會從 HTML 檔案的同目錄解析
python3 scripts/pdf.py md notes.md notes.pdf --page-size Letter
python3 scripts/pdf.py preview invoice.pdf --dpi 80 # 產生 invoice-page-1.png ... 並印出路徑
python3 scripts/pdf.py text report.pdf --pages 1-2
python3 scripts/pdf.py markdown report.pdf report.md # 任何 PDF 轉為 Markdown，保留表格和列表
python3 scripts/pdf.py info report.pdf # 頁數
python3 scripts/pdf.py merge all.pdf cover.pdf report.pdf
執行 python3 scripts/pdf.py <命令> --help 查看所有選項。從 Python 中，對應的呼叫為
pdfpecker.html_to_pdf(html, base_dir=...), html_file_to_pdf(path, out), markdown_to_pdf(text),
pdf_to_images(pdf, dpi=80), pdf_to_text(pdf), pdf_to_markdown(pdf), pdf_page_count(pdf), merge_pdfs([...])
和 pdf_to_pdfa(pdf, "out.pdf")（將現有 PDF 轉換為 PDF/A 格式以歸檔）。
編寫 HTML
當有適合的範本時，請從範本開始：templates/invoice.html（一頁發票，包含明細表格）和
templates/report.html（多頁報告，包含封面、頁碼、會重複表頭及 SVG 圖表的表格）。將其複製到輸出目錄旁並編輯。
請在 CSS 中設定頁面佈局，而非透過選項：
@page {
size: A4; /* 或 Letter、A5、"A4 landscape"、210mm 99mm */
margin: 18mm 16mm 20mm;
@bottom-center { content: "Page " counter(page) " of " counter(pages); font: 9pt sans-serif; color: #666; }
}
@page :first { @bottom-center { content: none; } }
h2 { break-after: avoid; } /* 保持標題與後續內容相連 */
tr, figure, .card { break-inside: avoid; }
.new-page { break-before: page; }
thead { display: table-header-group; } /* 在每一頁重複（<thead> 的預設行為） */
需注意的重點（詳情請見 reference.md）：
- 無 JavaScript。 腳本不會執行。請將圖表繪製為內聯 SVG 或 CSS（例如使用設定尺寸的
<div>作為長條圖），並在轉換前填入資料。 - 無網路連線。 圖片、樣式表和字型會從 HTML 檔案所在的資料夾 (
base_dir) 或data:URI 載入，絕不從 http(s) URL 載入。請先下載所需資源，或將其嵌入。 - 字型。 若未提供自訂字型，文字將使用 Helvetica (
sans-serif，等同 Arial)、Times (serif) 和 Courier (monospace)，並附帶內建的回退字型，這些字型涵蓋拉丁語、希臘語和西里爾字母。中文、日文、韓文、阿拉伯文、希伯來文、印度文、泰文及其他腳本會顯示為?，除非您提供包含這些文字的內嵌字型：--font NotoSansSC-Regular.otf（或使用--system-fonts來使用機器上安裝的字型）。若要指定特定字體，請使用@font-face搭配相對src。 - 現代 CSS 均可使用：flexbox、grid、表格、浮動、多欄、定位、變形、漸層、陰影、圓角、
object-fit、SVG、網頁字型、計數器和 CSS 變數。請如同為 Chrome 的列印預覽進行佈局；PdfPecker 遵循 Chrome 的佈局規則。 - 單位。 請使用
mm、pt或px（每英寸 96 px）。A4 內容寬度在 16 mm 邊距下為 178 mm（約 673 px）。
檢查結果
在交付 PDF 之前，請務必檢查頁面：執行 preview 並檢視 PNG 圖片。檢查是否有文字被截斷或溢出頁面、表格或標題在分頁處被不當分割、新頁面上只有孤零零的一行、空白頁面、? 出現在文字位置（缺少字型）以及未載入的圖片（路徑錯誤）。text 可以確認文字內容和順序。修正 HTML 或 CSS，再次轉換，並再次檢查。
錯誤
腳本會以狀態碼 1 退出並印出原因。從 Python 中，所有錯誤皆為 pdfpecker.PdfPeckerError：
PdfPeckerArgumentError（選項錯誤）、PdfReadError（檔案無法讀取為 PDF）、
PdfPasswordError、PdfLimitError（頁數過多）、PdfTimeoutError 和 PdfFileError（無法讀取字型或檔案）。