Pagination-first CSS engine (Python + Pango). Not headless Chrome: no JS, no RTL/bidi, print media default.
MANDATORY — read first when scope is unclear: references/resource-matrix.md
Load one flat expert lesson from references/ root (e.g. security-untrusted-html.md, css-paged-media.md). Do not open full-docs/ unless the matrix sends you there as last resort.
Before You Act
- Trust — Untrusted HTML/CSS? →
security-untrusted-html.md+security-url-fetcher.md(before code). - Runtime — CLI one-off (
cli-basics.md), batch, or embedded Python (python-instantiation.md)? - Output — Plain PDF, PDF/A/UA/X (
pdf-*.md), Factur-X, fillable forms? - Wrong tool? — JS layout, RTL, live DOM, pixel-perfect screen CSS → Puppeteer, not WeasyPrint.
Debug Bisect (wrong output)
debug-pipeline.md— enable logging; unsupported CSS fails silently by default.css-browser-vs-print.md— print vs browser gaps?- Closest sample from
resource-matrix.mdExamples catalog — ≤120 lines of relevant.css. - Still blocked? One matching flat lesson from the matrix.
full-docs/only as last resort (≤120 lines/§).
NEVER
- NEVER use positional string HTML or omit
base_urlonHTML(string=...)— seepython-instantiation.md. - NEVER enable
presentational_hintson untrusted HTML — CVE-2026-49452; seesecurity-untrusted-html.md. - NEVER expose untrusted HTML without process limits + fetcher blocking
file://. - NEVER set page size via imagined CLI flags — only
@pageor-s; seecli-basics.md. - NEVER assume PDF/A validity without
image-rendering: crisp-edges+ user-side validation — seepdf-a-archival.md. - NEVER expect
:hover,:focus,:visitedto match; NEVER rely on RTL/bidi — seecss-browser-vs-print.md. - NEVER use
zoom != 1casually — scales all units includingcmandA4. - NEVER bulk-load
full-docs/or example.pdffiles. - NEVER load
full-docs/contribute.mdorfull-docs/support.md.
Common Failures → Fix
| Symptom | Lesson |
|---|---|
cannot load library 'pango...' |
install-windows.md or install-macos.md + install-troubleshooting.md |
| Tofu / blank text | css-fonts.md |
| Broken relative assets | python-instantiation.md (base_url=) |
| Styles ≠ browser | css-browser-vs-print.md |
| Auth assets 404 | web-flask-django.md |
| PDF/A rejected | pdf-a-archival.md |
| SSRF / file read | security-url-fetcher.md |
| Slow batch renders | web-performance.md |
Platform Quick Pointers
| Platform | Start here |
|---|---|
| Linux | install-linux.md |
| Windows | install-windows.md |
| macOS | install-macos.md |
| Any install failure | install-troubleshooting.md |
Expert Notes
- Versions: major bumps change rendering — see
debug-version-upgrades.md; visual diff PDFs on upgrade. - Performance: cascade cost ∝ selectors × elements; multi-page tables are slow — see
web-performance.md. - Defaults:
presentational_hints=False;finisher(document, pdf)hooks pydyf before trailer.