PDF Generator

The PDF Generator extension creates polished, print-ready PDF documents from editable HTML sources. It's designed as a two-phase workflow: first create the HTML (optionally refined with the Design Extension), then render it to PDF — keeping the HTML source as an editable artifact.

Tools

Tool	Purpose
`pdf_validate_html`	Validate HTML before rendering — catch blocking errors and layout warnings
`pdf_generate`	Save editable HTML + render to PDF in one step
`pdf_render`	Re-render an existing HTML file to PDF after edits
`pdf_preview_html`	Render a PNG preview of HTML before PDF export

The Two-Phase Workflow

Phase 1: Create & Validate

First, the agent creates a complete HTML document. The pdf_validate_html tool checks:

Blocking errors — missing doctype, no <html> wrapper, no <body>, unclosed tags
Print CSS — checks for @page, fixed margins, break-inside avoidance, print-color-adjust
Remote assets — warns about external fonts/images that may not load offline
Pagination — warns about potential content overflow
Metadata — suggests <title> improvements

Phase 2: Render & Refine

// Generate PDF from HTML (saves HTML as an editable artifact)
pdf_generate {
  title: "Q3 Financial Report",
  html: "<!DOCTYPE html>...",
  outputName: "q3-report",
  format: "A4",
  orientation: "portrait"
}
// → Returns: HTML saved at .spectral/pdf/q3-report/index.html
// → PDF rendered at .spectral/pdf/q3-report/output.pdf
// → Manifest at .spectral/pdf/q3-report/manifest.json

// After editing the HTML, re-render without regenerating:
pdf_render {
  htmlPath: ".spectral/pdf/q3-report/index.html"
}

Integration with Design Extension

The PDF Generator works hand-in-hand with the Design Extension:

Pick a design system — designer_list_systems + designer_get_system
Load the workflow — designer_get_skill { name: "slide-deck" } (or any design artifact)
Build the HTML — follow the design skill's workflow exactly
Validate — pdf_validate_html to catch issues
Render — pdf_generate or pdf_render
Iterate — edit the HTML source and pdf_render again

Print CSS Best Practices

The validator enforces these print-quality rules:

Rule	Why
`@page { margin: ... }`	Fixed margins for consistent output
`break-inside: avoid` on sections	Prevents heading/widow orphans
`print-color-adjust: exact`	Preserves brand colors
`@page { size: A4 }`	Explicit page format
WOFF2 fonts (self-hosted)	Reliable font rendering

Render Options

Option	Values	Default
`format`	`A4`, `Letter`	`A4`
`orientation`	`portrait`, `landscape`	`portrait`
`printBackground`	`true`, `false`	`true`
`allowRemoteAssets`	`true`, `false`	`false`

Architecture

Agent Conversation
       │
       ▼
  pdf_* tools
       │
       ▼
  Chromium (Playwright) for rendering
       │
       ▼
  .spectral/pdf/{name}/index.html   ← editable source
  .spectral/pdf/{name}/output.pdf   ← rendered PDF
  .spectral/pdf/{name}/manifest.json ← metadata

When to Use

Reports — generate formatted PDF reports from data
Slide decks — convert HTML presentations to PDF
Invoices & documents — generate business documents
Design exports — render polished designs to shareable PDFs
Iterative refinement — edit the HTML and re-render without re-creating