Moonwalker1307/pdfpecker

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          # HTML 파일 옆에 있는 이미지와 CSS를 확인합니다
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 <command> --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)를 사용하며 번들로 제공되는 대체 폰트가 Latin, Greek 및 Cyrillic을 지원합니다. 중국어, 일본어, 한국어, 아랍어, 히브리어, 힌디어, 태국어 및 기타 스크립트는 해당 폰트를 전달하지 않으면 ?로 표시됩니다: --font NotoSansSC-Regular.otf (또는 --system-fonts를 사용하여 시스템에 설치된 폰트 사용). 특정 서체에 대해 상대 src를 사용한 @font-face를 사용하세요.
• 최신 CSS 작동: flexbox, grid, tables, floats, multi-column, positioning, transforms, gradients, shadows, rounded corners, object-fit, SVG, web fonts, counters 및 CSS 변수. Chrome의 인쇄 미리보기처럼 레이아웃하세요. PdfPecker는 Chrome의 레이아웃을 따릅니다.
• 단위. mm, pt 또는 px(인치당 96px)를 사용하세요. 16mm 여백의 A4 콘텐츠 너비는 178mm(약 673px)입니다.

결과 확인

PDF를 전달하기 전에 항상 페이지를 확인하세요: preview를 실행하고 PNG를 확인하세요. 텍스트가 잘리거나 페이지를 벗어나는지, 표나 제목이 페이지에 걸쳐 잘 분할되지 않는지, 새 페이지에 혼자 남은 마지막 줄이 없는지, 빈 페이지가 없는지, 문자가 ?로 표시되는지(폰트 누락), 이미지가 로드되지 않는지(잘못된 경로) 확인하세요. text 명령은 내용과 순서를 확인합니다. HTML 또는 CSS를 수정하고 다시 변환한 후 다시 확인하세요.

오류

스크립트는 상태 코드 1과 함께 오류 이유를 출력하고 종료합니다. Python에서는 모든 오류가 pdfpecker.PdfPeckerError입니다: 잘못된 옵션에 대한 PdfPeckerArgumentError, 읽을 수 없는 PDF 파일에 대한 PdfReadError, PdfPasswordError, PdfLimitError(페이지 수 초과), PdfTimeoutError, 읽을 수 없는 폰트나 파일에 대한 PdfFileError.