1# WeasyPrint PDF Generation Guidelines
2 
3## Overview
4 
5WeasyPrint converts HTML/CSS to PDF. These guidelines ensure professional output without awkward page breaks, orphaned content, or layout issues.
6 
7---
8 
9## Critical CSS Properties for Page Breaks
10 
11### Prevent Breaking Inside Elements
12 
13```css
14/* Apply to containers that should never split across pages */
15.executive-summary,
16.key-insight,
17.warning-box,
18.action-box,
19.diagram,
20.metrics-row,
21table {
22    page-break-inside: avoid;
23}
24 
25/* Tables are especially problematic - always prevent breaks */
26table {
27    page-break-inside: avoid;
28}
29 
30/* Two-column layouts */
31.two-col {
32    page-break-inside: avoid;
33}
34```
35 
36### Prevent Orphaned Headers
37 
38```css
39/* Headers should never appear at bottom of page without content */
40h2, h3, h4 {
41    page-break-after: avoid;
42}
43```
44 
45### Prevent Widows and Orphans in Text
46 
47```css
48p {
49    orphans: 3;  /* Minimum lines at bottom of page */
50    widows: 3;   /* Minimum lines at top of page */
51}
52```
53 
54---
55 
56## @page Rules
57 
58### Basic Setup
59 
60```css
61@page {
62    size: A4;
63    margin: 25mm 20mm 25mm 20mm;
64 
65    @top-center {
66        content: "Report Title";
67        font-family: Georgia, serif;
68        font-size: 9pt;
69        color: #666666;
70    }
71 
72    @bottom-center {
73        content: counter(page);
74        font-family: Georgia, serif;
75        font-size: 10pt;
76    }
77}
78 
79/* Suppress header on first page */
80@page :first {
81    @top-center { content: none; }
82}
83```
84 
85---
86 
87## Table Design for PDF
88 
89### Avoid Large Tables
90 
91- Keep tables under 8-10 rows when possible
92- Split large data sets into multiple smaller tables
93- Use `page-break-inside: avoid` on every table
94 
95### Table CSS
96 
97```css
98table {
99    width: 100%;
100    border-collapse: collapse;
101    margin: 12pt 0;
102    font-size: 9pt;
103    page-break-inside: avoid;
104}
105 
106th {
107    background: #1a1a1a;
108    color: white;
109    padding: 8pt 10pt;
110    text-align: left;
111    font-size: 8pt;
112    text-transform: uppercase;
113}
114 
115td {
116    padding: 8pt 10pt;
117    border-bottom: 0.5pt solid #d0d0d0;
118    vertical-align: top;
119}
120```
121 
122---
123 
124## Typography for Print
125 
126### Font Sizes (pt not px)
127 
128Use points for print, not pixels:
129 
130```css
131body {
132    font-family: Georgia, "Times New Roman", Times, serif;
133    font-size: 10pt;
134    line-height: 1.6;
135}
136 
137h1 { font-size: 22pt; }
138h2 { font-size: 14pt; }
139h3 { font-size: 11pt; }
140 
141/* Small text */
142.citation { font-size: 8pt; }
143.footer { font-size: 8pt; }
144.bib-entry { font-size: 8pt; }
145```
146 
147### Line Height
148 
149- Body text: 1.6-1.7
150- Tables: 1.4-1.5
151- Bibliography: 1.5
152 
153---
154 
155## Layout Patterns That Work
156 
157### Use `display: table` for Side-by-Side
158 
159Flexbox and Grid have limited WeasyPrint support. Use `display: table`:
160 
161```css
162.two-col {
163    display: table;
164    width: 100%;
165    page-break-inside: avoid;
166}
167 
168.col {
169    display: table-cell;
170    width: 50%;
171    padding: 10pt;
172    vertical-align: top;
173}
174 
175.col:first-child {
176    border-right: 0.5pt solid #cccccc;
177}
178```
179 
180### Metrics Dashboard
181 
182```css
183.metrics-row {
184    display: table;
185    width: 100%;
186    border: 1.5pt solid #000000;
187    page-break-inside: avoid;
188}
189 
190.metric {
191    display: table-cell;
192    width: 25%;
193    padding: 12pt 8pt;
194    text-align: center;
195}
196```
197 
198---
199 
200## Content Boxes
201 
202### Insight/Warning Boxes
203 
204```css
205.key-insight {
206    background: #f5f5f5;
207    border-left: 3pt solid #000000;
208    padding: 10pt 12pt;
209    margin: 12pt 0;
210    page-break-inside: avoid;
211}
212 
213.warning-box {
214    background: #1a1a1a;
215    color: white;
216    padding: 12pt 15pt;
217    margin: 12pt 0;
218    page-break-inside: avoid;
219}
220```
221 
222### Diagrams
223 
224```css
225.diagram {
226    background: #f5f5f5;
227    border: 1pt solid #000000;
228    padding: 12pt;
229    margin: 12pt 0;
230    text-align: center;
231    page-break-inside: avoid;
232}
233```
234 
235---
236 
237## Bibliography
238 
239```css
240.bibliography {
241    background: #f5f5f5;
242    padding: 15pt;
243    margin-top: 20pt;
244    border-top: 2pt solid #000000;
245}
246 
247.bib-entry {
248    margin-bottom: 8pt;
249    padding-left: 25pt;
250    text-indent: -25pt;
251    font-size: 8pt;
252    line-height: 1.5;
253    page-break-inside: avoid;
254}
255```
256 
257---
258 
259## Common Problems and Solutions
260 
261### Problem: Table Splits Across Pages
262 
263**Solution:** Add `page-break-inside: avoid` to table. If table is too large, split into multiple smaller tables.
264 
265### Problem: Header at Bottom of Page with No Content
266 
267**Solution:** Add `page-break-after: avoid` to all heading elements.
268 
269### Problem: Single Line at Top/Bottom of Page
270 
271**Solution:** Set `orphans: 3` and `widows: 3` on paragraphs.
272 
273### Problem: Flex/Grid Layout Breaks
274 
275**Solution:** Use `display: table` and `display: table-cell` instead.
276 
277### Problem: Images/Diagrams Cut Off
278 
279**Solution:** Add `page-break-inside: avoid` to container.
280 
281### Problem: Margins Too Tight
282 
283**Solution:** Use generous @page margins (25mm top/bottom, 20mm sides).
284 
285---
286 
287## Compact Report Strategy
288 
289To reduce page count while maintaining readability:
290 
2911. **Use 10pt base font** (not 12pt)
2922. **Tighter line-height**: 1.5-1.6 instead of 1.8
2933. **Smaller margins in boxes**: 10pt padding instead of 15pt
2944. **Condensed bibliography**: 8pt font, tighter spacing
2955. **Two-column layouts** for comparison data
2966. **Inline metrics dashboard** rather than full-width cards
297 
298---
299 
300## Validation Checklist
301 
302Before generating PDF, verify:
303 
304- [ ] All tables have `page-break-inside: avoid`
305- [ ] All boxed content has `page-break-inside: avoid`
306- [ ] Headers have `page-break-after: avoid`
307- [ ] Paragraphs have `orphans: 3; widows: 3`
308- [ ] No Flexbox or Grid in critical layouts
309- [ ] Font sizes in pt, not px
310- [ ] @page margins defined
311- [ ] Two-column layouts use `display: table`
312 
313---
314 
315## Generation Command
316 
317```bash
318weasyprint input.html output.pdf
319```
320 
321Options:
322- `--presentational-hints` - Respect HTML presentational hints
323- `-s stylesheet.css` - Apply external stylesheet
324- `--pdf-variant pdf/ua-1` - Generate accessible PDF
325