PDF Generation Skill

Professional PDF generation patterns using Typst, Puppeteer, and Sharp.

When This Applies

• Creating or modifying PDF generation code
• Working with Typst templates
• Debugging PDF output issues (text overlap, image sizing, page breaks)
• Implementing print-ready HTML
• Processing images for print (Sharp, EXIF, DPI)

Quick Reference

See adjacent files:

• reference.md - Typst syntax and patterns
• troubleshooting.md - Common issues and solutions

Core Patterns

1. Always Escape User Content

function escapeTypstString(str: string): string {
  if (!str) return "";
  return str
    .replace(/\\/g, "\\\\")  // Backslash first
    .replace(/"/g, '\\"')
    .replace(/\[/g, "\\[")
    .replace(/\]/g, "\\]")
    .replace(/#/g, "\\#")
    .replace(/\$/g, "\\$")
    .replace(/_/g, "\\_")
    .replace(/\*/g, "\\*")
    .replace(/@/g, "\\@")
    .replace(/</g, "\\<")
    .replace(/>/g, "\\>")
    .replace(/`/g, "\\`")
    .replace(/\n/g, " ")     // Newlines break template
    .replace(/\r/g, "")
    .replace(/\t/g, " ");
}

2. Constrain Image Dimensions

// Always specify both width AND height with fit: "contain"
#image("photo.jpg", width: 100%, height: 6in, fit: "contain")

3. Add Page Break Hints

// Before potentially tall content
#pagebreak(weak: true)

4. Use CSS Grid for Complex Layouts (HTML)

.page-one {
  display: grid;
  grid-template-columns: 1fr auto;
  grid-template-rows: auto 1fr auto;
}

5. Five-Tier PDF Fallback Chain

1. Typst WASM (primary - <100ms, professional)
2. Cloud PDF API (optional production fallback)
3. Puppeteer (dev only - system Chrome)
4. Print HTML (universal - works everywhere)
5. Emergency JSON (last resort - manual)

Key Libraries

Browser Tool Selection

Note: Puppeteer is still preferred for PDF generation because of its specialized page.pdf() API with precise control over margins, headers, footers, and print media. Use agent-browser for testing and verification.

Photo Processing Pipeline

// 1. Validate: Check data URI format
// 2. Resize: Max 2400px (8" @ 300dpi)
// 3. Fix EXIF: Auto-rotate based on orientation
// 4. Convert: sRGB color profile for print
// 5. Compress: JPEG 90% quality
// 6. Embed: Base64 data URI

Debugging Tips

1. Enable verbose logging:

   generateFieldReportPdf(report, photos, { verbose: true })

2. Check Typst diagnostics:

   generateFieldReportPdf(report, photos, { includeDiagnostics: true })

3. Common failure patterns:
   • Empty PDF buffer → Typst syntax error
   • Text overlap → Unescaped special characters
   • Image cutoff → Missing height constraint
   • Sidebar drift → Absolute positioning instead of Grid