pdf-best-practices（PDF 最佳实践）

PDF Best Practices Skill

Comprehensive guidelines for creating HTML that renders perfectly as PDF documents.

┌─────────────────────────────────────────────────────────────────────────────┐
│                         HTML to PDF Pipeline                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌──────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐  │
│   │  HTML    │───▶│  PDF Engine  │───▶│  Pagination │───▶│  Final PDF   │  │
│   │ Content  │    │  (Puppeteer) │    │  & Layout   │    │  Document    │  │
│   └──────────┘    └──────────────┘    └─────────────┘    └──────────────┘  │
│        │                                     │                              │
│        ▼                                     ▼                              │
│   ┌──────────┐                        ┌─────────────┐                       │
│   │  CSS     │                        │ Page Breaks │                       │
│   │  Styles  │                        │  & Margins  │                       │
│   └──────────┘                        └─────────────┘                       │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Quick Reference

Start Here

Building a new PDF document?

1. Start with Document Setup for the HTML structure
2. Review Page Breaks to prevent awkward splits
3. Check Content Density to avoid sparse pages

Working with data tables?

1. Read Tables for formatting and header repetition
2. Apply Page Breaks to prevent row splitting

Document has images?

1. Follow Images for sizing and positioning
2. Use Page Breaks to keep images with captions

Creating a specific document type?

1. Check Document Types for type-specific guidelines
2. Available types: Invoice, Report, Certificate, Letter, Table-heavy, Image-heavy

Default Configuration

When generating PDFs, use these recommended parameters:

{
  "format": "A4",
  "margin": {
    "top": "40px",
    "right": "40px",
    "bottom": "40px",
    "left": "40px"
  },
  "printBackground": true
}

Quick Checklist

Before generating any PDF:

• Complete HTML structure with DOCTYPE, html, head, body
• CSS includes @page rule with A4 size
• Body has -webkit-print-color-adjust: exact
• All images have explicit width/height
• Tables use thead/tbody structure
• page-break-inside: avoid on logical content blocks
• Headings have page-break-after: avoid
• No excessive whitespace or sparse pages
• Font sizes are 9pt or larger
• Colors have sufficient contrast
• pdfParams includes format, margins, and printBackground: true