The Complete Production SOP: How to Deploy and Run WeasyPrint Modern HTML to Print PDF in Autonomous AI Agents
Step-by-step SOP to install and run WeasyPrint Modern HTML to Print PDF in Codex, Claude Code, and Cursor. Master CSS paged media, breaks, and headers.
Technical Overview & Architectural Context
Autonomous coding agents frequently fail when tasked with generating publication-grade PDF documents from HTML. Typical LLM pitfalls include relying on headless Chrome instances (Puppeteer/Playwright) which exhaust sandbox memory, or improperly writing raw CSS without considering CSS Paged Media Level 3 specifications. When generating invoices, reports, or legal agreements, agents often leave dangling table headers, severed signature lines across page breaks, and broken counter increments for multi-page headers and footers. The 'weasyprint-html-print-pdf' skill provides strict declarative constraints and deterministic workflows. It forces agents to leverage WeasyPrint's standards-compliant rendering engine with CSS Paged Media constructs like @page rules, margin boxes, 'break-inside: avoid', and dynamic counters. By anchoring the agent to proven Python-based WeasyPrint invocation patterns and CSS architecture, teams eliminate document rendering hallucinations and non-deterministic visual defects.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the skill manifest directory and inject verified procedural rules into the agent runtime path.
Autonomous runtimes such as Claude Code, Codex, and Cursor monitor predefined directories for `.agents/skills` or `.claude/skills`. Installing the `weasyprint-html-print-pdf` skill exposes the frontmatter YAML triggers directly to the LLM orchestrator, enabling immediate hot-reloading without IDE restarts.
mkdir -p ~/.agents/skills/weasyprint-html-print-pdf && curl -fsSL https://askills.dev/api/skills/weasyprint-html-print-pdf/raw -o ~/.agents/skills/weasyprint-html-print-pdf/SKILL.md---
name: "weasyprint-html-print-pdf"
description: "Render modern HTML5 and CSS3 documents directly into print-perfect PDF files."
metadata:
author: "Kozea"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "convert html to pdf weasyprint"
- "css paged media page break"
- "add headers and footers weasyprint"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Use symlinks between `~/.agents/skills/` and project-specific `.cursor/rules/` to avoid duplicating SKILL.md across repositories.
Ensure that `fs_write` is scoped to the workspace directory. Restrict agent execution from writing arbitrary binary assets to root system directories.
Native System Libraries & Python Dependency Validation
Ensure WeasyPrint's underlying C libraries (Pango, Cairo, GDK-PixBuf) are installed and isolated within the sandbox.
WeasyPrint relies on system-level graphics and typography engines. If libcairo or libpango headers are absent, agent executions will throw dynamic loader errors. Install the required binaries and Python packages before invoking the skill.
# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 libgdk-pixbuf2.0-0
# macOS
brew install pango cairo gdk-pixbuf libffi
# Python environment
python -m venv .venv && source .venv/bin/activate && pip install weasyprintSet `FONTCONFIG_PATH=/etc/fonts` in containerized workspaces to ensure WeasyPrint can resolve system web fonts without network lookups.
Do not pass user-controlled unsanitized HTML containing `<link rel='stylesheet'>` with external URLs when `net_access: false` is enforced in the skill frontmatter.
Intent Matching & Trigger Invocation
Verify deterministic activation using tested natural language prompts matching the skill triggers.
Agent orchestrators continuously evaluate user instructions against registered triggers. Using trigger keywords like 'convert html to pdf weasyprint' or 'css paged media page break' loads the procedural SOP rules directly into the working context.
python -c "import weasyprint; print(f'WeasyPrint {weasyprint.__version__} Ready')"Anchor prompts with explicit references to CSS Paged Media specifications to prevent the LLM from falling back to headless browser automation.
Avoid ambiguous trigger requests such as 'make me a PDF' without mentioning WeasyPrint or HTML rendering, which may trigger generic print tools.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks and layout verification before accepting generated PDFs.
The skill mandates that the agent verify its output using Python assertions and syntax validation. The agent must test for page overflow, check exit codes, and verify file size to guarantee rendering completion.
python -c "from weasyprint import HTML; doc = HTML('invoice.html').render(); print(f'Document rendered successfully with {len(doc.pages)} pages')"Check `len(doc.pages)` programmatically to catch unexpected page breaks caused by unconstrained margins.
Always inspect the terminal exit code (`echo $?`); WeasyPrint may emit non-fatal warnings for minor CSS syntax errors that still need agent review.
Real-World Scenario: Automated Multi-Page Invoice Generation with CSS Paged Media Headers and Avoided Breaks
“Use weasyprint to convert html to pdf for our quarterly executive invoice. Ensure we use CSS paged media page break rules to keep the itemized table rows and summary signature card from breaking across pages, and add headers and footers with dynamic page counters.”
Runtime Troubleshooting & Failure Modes
Root Cause: WeasyPrint cannot locate the native Pango or Cairo shared libraries on the host system dynamic link path (frequently occurring on macOS Apple Silicon or minimal Docker images).
export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix)/lib:$DYLD_FALLBACK_LIBRARY_PATH" && pip install --force-reinstall weasyprintRoot Cause: The agent used obsolete CSS2 print rules instead of modern CSS Paged Media Level 3 `break-inside: avoid;` syntax.
/* Replace legacy page-break declarations with standard CSS Paged Media properties */
.table-row, .card {
break-inside: avoid;
page-break-inside: avoid; /* backward compatibility fallback */
}Frequently Asked Questions (WeasyPrint Modern HTML to Print PDF SOP)
Q:Can I use WeasyPrint Modern HTML to Print PDF across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. By mounting the definition into the standard agents directory (~/.agents/skills) or project-level rules folders, Codex, Claude Code, Cursor, and Windsurf can instantly interpret its triggers and execution rules.
Q:How does WeasyPrint Modern HTML to Print PDF prevent context window overflow during long agent sessions?
The skill provides concise, highly targeted CSS Paged Media patterns rather than massive documentation dumps. It explicitly tells the agent how to configure `@page`, manage page numbers with `counter(page)`, and isolate element boundaries, eliminating lengthy back-and-forth prompt iterations.
Q:Does this skill require escalated root or container permissions?
No. The skill is rated with a Security Score of 98/100. It requires read and write permissions limited solely to the active workspace directory, with network access disabled (`net_access: false`) to safeguard against remote resource exfiltration during PDF compilation.
Ready to equip your autonomous agent with WeasyPrint Modern HTML to Print PDF?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.