pdf-best-practices

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

I want to...	Read this
Set up document structure correctly	Document Setup
Control page breaks	Page Breaks
Format tables for PDF	Tables
Handle images properly	Images
Optimize content density	Content Density
Set up colors and backgrounds	Colors & Backgrounds
Add headers, footers, page numbers	Headers & Footers
Create specific document types	Document Types

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