Create Pdf

Guidelines for creating professional, visually distinctive PDF reports via python-pptx's PDFReport helper class and matplotlib.

The design language borrows from modern presentation aesthetics — clean, spacious, intentional — adapted for the long-form reading experience. Light body pages for readability, bold title treatment for impact, and strategic color throughout.

Reference Files

Read these from /tmp/skills/pdf/references/ when you need implementation details.

---

1. Design Philosophy

Every element earns its place on the page. If it doesn't communicate, clarify, or guide the eye — remove it.

1.1 Core Principles

Content is king. Typography, spacing, and strategic color create hierarchy. Decoration is the enemy. A well-structured report with generous whitespace communicates more authority than one stuffed with borders and ornaments.

Light body, bold accents. Reports are read at length — light backgrounds with dark text for body content. Save bold, dark treatment for the title page and section openers. The title page sets the mood; body pages prioritize readability.

60/30/10 color distribution. 60% neutral (white page background, dark body text), 30% complementary (card/callout fills, section header colors, table header bands), 10% accent (KPI values, chart highlights, key stats, accent bars on callout boxes). If accent color covers more than ~10% of a page's visual area, pull back.

Topic-driven palette. The palette should feel designed for THIS report's subject. If swapping colors into a completely different report would still "work," the choices aren't specific enough. One color dominates (titles, section headers), 1–2 supporting tones for callout fills and tables, one accent for highlights.

Generous whitespace. Let content breathe. When a section feels cramped, split it across two pages rather than shrinking fonts. Space between sections signals confidence, not waste.

Two font weights only. Regular for body, Bold for headings and emphasis. Helvetica covers both. Reserve Italic for quotes and captions only — it's a third voice, use it sparingly.

Flat and clean. No heavy borders, drop shadows, 3D chart effects, or decorative clip art. Subtle background fills, minimal or no borders, and clean lines. Hierarchy comes from size, weight, color, and spatial position — in that order.

Visual motif. Commit to ONE distinctive element and carry it through every page: a colored left-margin bar on callout boxes, accent lines under headings, numbered circle badges for key items, or a consistent card styling. One motif, applied everywhere, creates more design coherence than multiple decorative ideas applied inconsistently.

Layout variety. No two consecutive sections should use the same visual format. Rotate through prose, callout boxes, charts, tables, KPI strips, quotes, and numbered/labeled items. Plan the visual treatment for each section before writing code.

1.2 What Looks Outdated

1.3 Accessibility & Contrast

WCAG minimums: Body text (<18pt): 4.5:1 contrast ratio. Headings (≥18pt or ≥14pt bold): 3:1.

Safe on white/light: #000000, #333333, #1B2A4A, #4A4A4A. On dark backgrounds (title page): #FFFFFF, #E0E0E0.

Avoid: light gray text on white, pastel text on light backgrounds, red (#FF0000) on white (only 4:1 — fails for small text). Never use color as the sole information channel.

---

2. Theme & Color System

2.1 Built-In Themes

Each theme defines title/heading color, accent color, card/callout background, and body text. Apply via pdf.set_theme('name').

2.2 Custom Palettes

For subjects that don't fit a built-in theme, set colors directly:

pdf.COLORS['title'] = (30, 39, 97)
pdf.COLORS['accent'] = (100, 140, 200)
pdf.COLORS['card_bg'] = (240, 244, 248)
pdf.COLORS['body'] = (51, 51, 51)
pdf.COLORS['border'] = (200, 210, 220)

Derive card_bg from the title color at ~5–10% opacity over white. The accent should complement but not match the title color — a different hue or a lighter/brighter version of the same family.

2.3 Chart Palette Integration

Always harmonize charts with the report palette:

pal = pdf.get_chart_palette()
# pal['primary']    — hex, main chart color
# pal['secondary']  — hex, accent chart color
# pal['series']     — list of 6 harmonized hex colors
# pal['title_hex']  — for chart titles
# pal['body_hex']   — for axis labels
# pal['card_bg_hex'] — for chart background fills

Pass pal['series'] to bar colors, line colors, pie slices, etc. Charts that use default matplotlib colors instead of the report palette look disconnected.

---

3. Script Toolkit

3.1 Loading

import sys, importlib
sys.path.insert(0, '/tmp/skills/pdf/scripts')
from pdf_helpers import PDFReport, THEMES, render_formula

3.2 Initialization

pdf = PDFReport(orientation='P', unit='mm', format='A4')
pdf.set_auto_page_break(auto=True, margin=25)
pdf.set_margins(left=20, top=20, right=20)
pdf.set_theme('ocean')
pdf.alias_nb_pages()

3.3 Helper Method Overview

For detailed signatures, usage notes, and the add_code_block() standalone function, see references/components.md.

3.4 Font Size Guide

Use Helvetica (built into fpdf2). One font family is enough — hierarchy comes from size and weight.

---

4. Report Planning & Structure

4.1 Before Writing Code

Clarify purpose (informational, analytical, persuasive, status update) and audience (executives want brevity and conclusions first, technical readers want methodology and detail). Outline the sections, decide which visual treatment each gets (prose, callout, chart, table, KPI strip, badges), and plan a target page count.

4.2 Recommended Section Order

1. Title Page — add_title_page() with dark header band, subtitle, author, date 2. Executive Summary — Purpose, key findings, conclusions, recommendations. Write LAST, place FIRST. 3. Introduction / Background — Context, scope, objectives 4. Methodology (if applicable) — Data gathering approach, kept brief 5. Findings / Analysis — Core content with charts, organized by theme/chronology/priority 6. Discussion (if applicable) — Interpret findings, address limitations 7. Conclusions — Main takeaways 8. Recommendations (if applicable) — Specific, actionable next steps 9. Appendix / References (if applicable)

Lead with conclusions (inverted pyramid). One idea per section. Executive summary should stand alone at ~10–15% of total text content.

4.3 Special Report Types

Executive / Status: 3–5 sections, lead with KPI strip, outcomes and next steps. Keep it short.

Analytical / Research: Detailed, includes methodology and discussion, line charts and tables, addresses limitations.

Comparison / Benchmark: Structured around dimensions, uses grouped bar/radar charts, ends with clear recommendation.

Incident / Post-Mortem: Chronological, factual, blameless tone.

---

5. Writing Style

Clear, direct language. Sentences under 25 words, paragraphs under 75 words. Active voice preferred.

Be specific: "Revenue increased 18% YoY to $4.2M" communicates more than "Revenue increased significantly."

Professional, objective tone — confident but measured. Consistent formatting for numbers, currencies, and percentages. Always provide context for numbers: comparisons, benchmarks, or trends.

---

6. Chart Sections — Tell the Story, Not Just the Data

<chart_section_composition> A chart without interpretation is a missed opportunity. Every chart section in a report pairs the visualization with a clear takeaway — the chart is evidence for an insight, and the insight should be stated explicitly.

Every chart section includes:

1. An insight-driven heading — frames what the data reveals. "Revenue Grew 18% as Enterprise Segment Doubled" communicates far more than "Revenue Overview."

2. Brief context — 1–2 sentences before the chart that set up what the reader should look for.

3. The chart itself — styled to match the report palette, saved at dpi=150+, with descriptive axis labels.

4. A "Figure N:" caption — sequentially numbered, placed via add_chart(img_path, caption).

5. A takeaway paragraph after the chart — what the data means, why it matters, what action it implies. This is where the analysis lives.

The pattern is: heading → context sentence → chart → caption → analysis paragraph. A section with just a heading and a chart leaves the reader to draw their own conclusions, which defeats the purpose of the report. </chart_section_composition>

For chart type selection, matplotlib styling, and palette integration details, see references/charts.md.

---

7. Layout & Pagination

7.1 Content Density

One key idea per section. Prefer a single clear chart over three small ones. Generous whitespace between sections. When a section feels cramped, split across two pages.

7.2 Page-Break Safety

Composite elements (callout boxes, KPI strips, charts, tables) that draw background fills at absolute Y positions produce rendering artifacts when multi_cell() triggers an auto page break mid-element. All built-in helpers handle this via ensure_space(). When building custom composite elements, call pdf.ensure_space(estimated_height) before drawing.

For detailed technical rules on page breaks, the write/multi_cell overflow problem, code blocks, and FPDF encoding limitations, see references/technical.md.

7.3 Layout Variety

Plan the visual treatment for each section before writing code. Use this as a rotation guide:

No two consecutive sections should use the same format. If the last section was a chart, make the next one a callout box or table.

---

8. QA Checklist

1. Theme chosen — topic-driven palette applied via set_theme() or custom COLORS 2. Chart palette used — get_chart_palette() colors passed to all matplotlib charts 3. Visual motif consistent — same accent treatment on every page 4. Layout variety — no two consecutive sections use the same visual format 5. Title page present with dark header band, title, author, date 6. Executive summary stands alone 7. Logical section flow with coherent narrative arc 8. All data/numbers verified for accuracy 9. Each chart has dpi=150+, palette-harmonized colors, and sequential "Figure N:" caption 10. Every chart section includes context before and takeaway after the chart 11. Consistent fonts, colors, and spacing throughout 12. Tables have themed headers and alternating row shading 13. Page numbers via alias_nb_pages() 14. set_auto_page_break enabled 15. matplotlib.use('Agg') set before pyplot import 16. plt.close() called after each chart save 17. No write() + multi_cell(fixed_width) patterns (use add_indented_rich_text) 18. No manual rect + multi_cell combos without ensure_space() (use built-in helpers) 19. Code/preformatted text uses add_code_block() — never add_body() for multiline code 20. WCAG contrast met — body text ≥4.5:1, headings ≥3:1 21. No outdated patterns — no heavy borders, 3D charts, clip art, rainbow colors 22. File saved to /tmp/ and generate_download_link called

Chart Creation for PDF Reports

1. Chart Section Composition

A chart in a report is evidence for a claim. Every chart section follows this pattern:

Heading → Context → Chart → Caption → Analysis

1. Insight-driven heading: "Revenue Grew 18% as Enterprise Deals Doubled" rather than "Revenue Chart" 2. Context sentence(s): 1–2 lines before the chart that set up what the reader should look for 3. The chart: matplotlib image, palette-harmonized, clean styling 4. Figure caption: sequential numbering via add_chart(path, caption='Figure N: ...') 5. Analysis paragraph: what the data means, why it matters, what action it implies

pdf.add_section('Revenue Performance')
pdf.add_body('After restructuring the sales team in Q2, enterprise revenue began accelerating. '
             'The chart below shows quarterly performance by segment.')
pdf.add_chart('/tmp/revenue.png', caption='Figure 1: Revenue by segment, Q1–Q4 2024')
pdf.add_body('Enterprise revenue grew 18% YoY, driven primarily by expansion into the APAC region. '
             'SMB remained flat, suggesting the new pricing model has not yet gained traction in that segment.')

A section with just a heading and a chart image leaves the reader to draw their own conclusions, which undermines the report's analytical value.

---

2. Choosing the Right Chart Type

When in doubt, use a bar chart — it's the most universally understood.

---

3. Matplotlib Styling for PDF

3.1 Palette Integration

Always use the report's theme colors for charts. Disconnect between chart colors and report colors looks unprofessional.

import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt

pal = pdf.get_chart_palette()
# pal['primary']     — hex, title/heading color
# pal['secondary']   — hex, accent color
# pal['series']      — list of 6 hex colors, harmonized with theme
# pal['title_hex']   — for chart title text
# pal['body_hex']    — for axis labels and tick text
# pal['card_bg_hex'] — for chart background fill

3.2 Clean Chart Template

fig, ax = plt.subplots(figsize=(7, 4))

# Style
ax.set_facecolor('#FFFFFF')
fig.patch.set_facecolor('#FFFFFF')

# Remove unnecessary spines
for sp in ['top', 'right']:
    ax.spines[sp].set_visible(False)
for sp in ['left', 'bottom']:
    ax.spines[sp].set_color('#CCCCCC')

# Light grid
ax.grid(axis='y', alpha=0.3, color='#CCCCCC')
ax.set_axisbelow(True)

# Tick styling
ax.tick_params(colors='#555555', labelsize=9)

# Title and labels
ax.set_title('Insight-Driven Title', fontsize=13, fontweight='bold',
             color=pal['title_hex'], pad=12)
ax.set_ylabel('Y Label', fontsize=10, color='#666666')

# ... plot data using pal['series'] colors ...

plt.tight_layout()
plt.savefig('/tmp/chart.png', dpi=150, bbox_inches='tight', facecolor='#FFFFFF')
plt.close()

3.3 Rules

Always call matplotlib.use('Agg') BEFORE importing pyplot. Always plt.close() after saving. Save at dpi=150 or higher. Use figsize=(7, 4) for good A4 fit. Always tight_layout(). No 3D effects.

Descriptive, insight-driven titles on charts. Label axes clearly. Abbreviate long labels ("Jan" not "January", "$4.2M" not "$4,200,000").

3.4 Chart Type Notes

Bar charts: Space bars with width=0.6 or less. Add value labels on top of bars for key values. Use zorder=3 on bars, zorder=0 on grid.

Line charts: Use markers (marker='o', markersize=5) for data points. 2–3 series max for clarity. Add fill_between at low alpha for area emphasis.

Pie/Donut: startangle=90, counterclock=False for consistent orientation. ≤5 slices. For donut: wedgeprops=dict(width=0.4). Use autopct='%1.0f%%'.

Horizontal bar: ax.invert_yaxis() so highest value is at top. Add inline value labels with ax.text().

Stacked bar: Use bottom parameter to stack. Include a clear legend — ax.legend(loc='upper left', frameon=False).

---

4. Legend Placement

Place legends where they don't overlap data.

Preferred (below chart): ax.legend(loc='upper center', bbox_to_anchor=(0.5, -0.12), ncol=3, frameon=False, fontsize=9)

Alternative (right): ax.legend(bbox_to_anchor=(1.02, 1), loc='upper left', frameon=False)

Always frameon=False for clean look.

---

5. Mathematical Formula Rendering

from pdf_helpers import render_formula

render_formula(r'\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}', '/tmp/formula.png')
pdf.add_formula('/tmp/formula.png')

Uses Computer Modern font, 15pt, 250 DPI, transparent background by default. Override with fontsize and dpi params. Note: matplotlib's mathtext does NOT support \begin{pmatrix}, \begin{align}, or other LaTeX environments — only inline math expressions.

Component Reference & Visual Patterns

This reference covers the PDFReport helper methods in detail, the standalone add_code_block() function, and custom component patterns for building modern, visually distinctive reports.

---

1. Content Methods — Detailed Reference

add_title_page(title, subtitle="", author="", date="", org="")

Dark header-band title page with white text. The band covers the top ~130mm. Subtitle, author, org, and date are optional — meta fields appear below the band.

pdf.add_title_page(
    'Q4 2024 Performance Report',
    subtitle='Enterprise Division Analysis',
    author='Strategy Team',
    date='January 2025'
)

add_section(title) / add_subsection(title)

Section: 18pt bold in title color, accent underline from x=20 to x=80. Subsection: 14pt bold, no underline. Both reset text color to body afterward.

Use add_section() for major report divisions. add_subsection() for topics within a section.

add_body(text)

Standard body paragraph, 11pt regular, body color. Uses multi_cell(0, 6, text) — safe for single-block prose. Do NOT use for multiline code (FPDF drops \n in multi_cell).

add_callout_box(text, fill_color=None, min_height=30)

Tinted background box with a 2.5mm accent-colored bar on the left edge. Page-break safe via ensure_space(). Default fill is the theme's card_bg color.

Good for: key findings, important notes, summary takeaways, warnings.

pdf.add_callout_box("Key finding: Customer retention improved 12% after implementing the new onboarding flow.")

For a custom fill color (e.g. a warning box):

pdf.add_callout_box("Warning: Data for Q3 is preliminary.", fill_color=(255, 245, 238))

add_quote_strip(text, attribution="")

Centered italic text in a full-width tinted band. Optional attribution line in smaller muted text. Good for key quotes, executive summaries, or section-closing takeaways.

pdf.add_quote_strip(
    "The best time to plant a tree was twenty years ago. The second best time is now.",
    attribution="— Chinese Proverb"
)

add_kpi_strip(kpis, cols=None)

Row of stat callout cards. Each card shows a large bold value in title color and a small muted label. cols defaults to the number of KPIs.

pdf.add_kpi_strip([
    {'label': 'Revenue', 'value': '$4.2M'},
    {'label': 'Growth', 'value': '+18%'},
    {'label': 'NPS Score', 'value': '72'},
])

Best at the top of a section or right after the executive summary heading. 3–4 KPIs per strip works best; more gets cramped.

add_indented_rich_text(indent_x, bold_text, regular_text, ...)

Bold + regular text inline at an indented position. Uses write() for both parts with a temporary left-margin shift. This is the safe pattern for mixing font weights at an indent — see references/technical.md for why write() + multi_cell() doesn't work.

pdf.add_indented_rich_text(28, "Key Insight: ", "The enterprise segment drove 73% of total growth.")

add_labeled_item(indent_x, indicator_color, label, description, ...)

Colored indicator bar (2mm × 6mm) + bold label + regular description. Good for pros/cons, categorized points, or feature lists.

pdf.add_labeled_item(28, (44, 95, 45), "Strength", "Market-leading retention rates in the 25-34 demographic.")
pdf.add_labeled_item(28, (200, 60, 60), "Risk", "Supply chain dependency on a single vendor.")

add_numbered_item(indent_x, number, badge_color, label, description, ...)

Numbered badge (8mm × 7mm rectangle with white number) + bold label + description. Good for step-by-step processes, ranked items, or numbered recommendations.

pdf.add_numbered_item(32, 1, (6, 90, 130), "Audit Existing Infrastructure",
    "Map all current services and their dependencies before migration planning.")

add_chart(img_path, caption="", width=160)

Centers a chart image with optional "Figure N:" caption below. Estimates image height and calls ensure_space(). Default width 160mm (centered on A4).

pdf.add_chart('/tmp/revenue_chart.png', caption='Figure 1: Revenue by segment, Q1-Q4 2024')

add_table(headers, rows, col_widths=None, row_height=7)

Themed table with header band in title color, alternating row shading. Uses cell() — long text is clipped, not wrapped. For wrapping, use add_table_wrapped().

pdf.add_table(
    headers=['Metric', 'Q3', 'Q4', 'Change'],
    rows=[['Revenue', '$3.6M', '$4.2M', '+18%'], ['Users', '12.4K', '14.1K', '+14%']],
    col_widths=[50, 35, 35, 30]
)

add_table_wrapped(headers, rows, col_widths=None, line_height=5.5, padding=1.5)

Table with automatic multi-line cell wrapping. Row height adjusts to the tallest cell. Use this when any cell might contain more than a few words.

add_formula(img_path, max_w=90)

Embeds a rendered formula image (from render_formula()) in a tinted strip, centered.

---

2. Code Block Implementation

add_code_block() is a standalone function — not built into PDFReport. Paste this into your script and call it on the pdf instance for any code, shell commands, JSON, config files, or preformatted text.

def add_code_block(pdf, code_text: str, font_size: int = 8, line_height: float = 4.5):
    """
    Render monospace code with a dark background, preserving all line breaks.
    FPDF2 does not respect \\n in multi_cell/write — this function splits on \\n
    and renders each line individually with cell(), which is the only safe approach.
    """
    lines = code_text.strip('\n').split('\n')
    estimated_h = len(lines) * line_height + 6
    pdf.ensure_space(estimated_h)

    pdf.set_fill_color(30, 41, 59)      # dark slate background
    pdf.set_text_color(226, 232, 240)    # light text
    pdf.set_font('Courier', '', font_size)

    pdf.ln(1)
    for line in lines:
        display = line.replace(' ', '\u00a0')  # preserve indentation
        pdf.cell(0, line_height, display, ln=True, fill=True)
    pdf.ln(3)

    # Restore body font and color
    pdf.set_font('Helvetica', '', 11)
    pdf.set_text_color(51, 51, 51)

Usage:

add_code_block(pdf, """
def review_router(state):
    if state["review_report"].status == "PASS":
        return "finalize"
    return "builder_agent"
""")

Rules:

Do not pass multiline strings to add_body(), write(), or multi_cell() — FPDF2 silently drops all \n characters, collapsing the block into one continuous line. Always use add_code_block() for preformatted content. If a code block exceeds ~40 lines, split into labeled parts rather than letting it run across pages.

---

3. Visual Motif Ideas

Pick ONE motif and apply it consistently across every page. Mixing motifs looks scattered.

Accent-bar callouts (default): The add_callout_box() left-bar pattern. Extend this by using the same left-bar treatment on other custom elements — e.g., adding a 2.5mm accent bar beside important paragraphs or beside chart annotations.

Numbered badges: Use add_numbered_item() for key points, recommendations, or steps. The badge color should match the theme's title color. Creates a strong visual rhythm when 3–5 items appear in sequence.

Indicator-bar categorization: Use add_labeled_item() with consistent color coding (green for strengths, amber for opportunities, red for risks). Apply the same colors in charts and tables.

Accent-underlined sections: The default add_section() draws an accent line under the heading. Carry a similar short accent line under subsections or key terms for consistency.

Full-width tinted bands: Use add_quote_strip() for section-closing takeaways, not just quotes. A tinted band with centered text creates visual punctuation between major sections.

---

4. Custom Component Patterns

When the built-in helpers don't cover what you need, build custom elements using FPDF primitives. Key rules: always call ensure_space() first, always reset font/color after, and keep the styling consistent with the theme.

Custom two-column layout:

pdf.ensure_space(50)
col_w = 80
gap = 10
y0 = pdf.get_y()

# Left column
pdf.set_xy(20, y0)
pdf.set_font('Helvetica', 'B', 14)
pdf.set_text_color(*pdf.COLORS['title'])
pdf.cell(col_w, 8, 'Before', ln=True)
pdf.set_x(20)
pdf.set_font('Helvetica', '', 10)
pdf.set_text_color(*pdf.COLORS['body'])
old_l = pdf.l_margin
pdf.set_left_margin(20)
pdf.multi_cell(col_w, 5.5, 'Description of the before state...')
pdf.set_left_margin(old_l)

# Right column
pdf.set_xy(20 + col_w + gap, y0)
pdf.set_font('Helvetica', 'B', 14)
pdf.set_text_color(*pdf.COLORS['title'])
pdf.cell(col_w, 8, 'After', ln=True)
pdf.set_x(20 + col_w + gap)
pdf.set_font('Helvetica', '', 10)
pdf.set_text_color(*pdf.COLORS['body'])
pdf.set_left_margin(20 + col_w + gap)
pdf.multi_cell(col_w, 5.5, 'Description of the after state...')
pdf.set_left_margin(old_l)

pdf.set_y(max(pdf.get_y(), y0 + 40))

Section divider page (for long reports):

pdf.add_page()
pdf.set_fill_color(*pdf.COLORS['title'])
pdf.rect(0, 0, 210, 297, 'F')
pdf.set_y(120)
pdf.set_text_color(255, 255, 255)
pdf.set_font('Helvetica', 'B', 28)
pdf.cell(0, 14, 'Part II', align='C', ln=True)
pdf.set_font('Helvetica', '', 16)
pdf.set_text_color(210, 225, 240)
pdf.cell(0, 10, 'Market Analysis', align='C', ln=True)

Highlight stat inline (accent-colored number in body text):

pdf.set_font('Helvetica', '', 11)
pdf.set_text_color(*pdf.COLORS['body'])
pdf.write(6, 'Customer retention improved by ')
pdf.set_font('Helvetica', 'B', 13)
pdf.set_text_color(*pdf.COLORS['title'])
pdf.write(6, '12%')
pdf.set_font('Helvetica', '', 11)
pdf.set_text_color(*pdf.COLORS['body'])
pdf.write(6, ' in the first quarter after deployment.')
pdf.ln(8)

Technical Reference — FPDF Pitfalls & Rules

This reference covers the technical gotchas that cause the most common bugs in PDF generation with fpdf2. Load this when building custom layouts or troubleshooting rendering issues.

---

1. Page-Break Safety

The Problem

Composite elements (callout boxes, KPI strips, charts, tables) draw background fills or accent bars at absolute Y positions. If multi_cell() triggers an auto page break mid-element, the Y reference captured before the break becomes invalid on the new page. This causes fills and bars to stretch incorrectly or appear in the wrong position.

The Fix

Call pdf.ensure_space(estimated_height_mm) before drawing any composite element. This checks remaining vertical space and forces a clean page break BEFORE the element starts, so no element ever straddles a page boundary.

pdf.ensure_space(50)  # ensure 50mm of space before drawing
y0 = pdf.get_y()
# ... draw background rect, write text, etc. ...

All built-in helpers (add_callout_box, add_kpi_strip, add_chart, add_table, add_table_wrapped, add_numbered_item, add_labeled_item, add_quote_strip, add_formula) already call ensure_space() internally. You only need to call it manually when building custom composite elements.

Rules

Do not draw a background rect, then write text that may trigger a page break, then calculate rect height from Y positions — the Y delta is invalid across pages. Always ensure_space() first, or pre-calculate the element's total height and check against available space.

---

2. write() + multi_cell() Overflow

The Problem

When combining bold titles with regular descriptions at an indented position, a common pattern is:

pdf.write(6, "Bold Title: ")           # advances cursor rightward
pdf.multi_cell(fixed_width, 6, "Long description text...")  # starts from cursor X

This overflows because write() advances the X cursor, and multi_cell(fixed_width) adds that fixed width starting from the new X position — extending past the right page margin. Text gets clipped.

The Fix

Use add_indented_rich_text(), which uses write() for BOTH the bold and regular parts with a temporary set_left_margin():

pdf.add_indented_rich_text(28, "Bold Title: ", "Long description text that wraps correctly.")

Rules

Do not follow write() with multi_cell(fixed_width) — it overflows the page. Use write() for both bold and regular parts when combining inline. Set a temporary left_margin to the indent position and restore it afterward. multi_cell(0, h, text) (width=0, meaning "fill to right margin") is safe for non-indented body text.

---

3. Code Block Line Breaks

The Problem

FPDF2's multi_cell() and write() silently drop all \n characters. Passing a multiline code string to add_body() or any multi_cell()-based method collapses the entire block into one continuous line of text.

The Fix

Use add_code_block() (standalone function — see references/components.md for the implementation). It splits on \n and renders each line individually with cell(), which is the only reliable approach.

Rules

Never pass multiline strings to add_body(), write(), or multi_cell() when line breaks matter. Always use add_code_block() for code samples, shell commands, JSON, config files, or any preformatted text. Call ensure_space() before rendering (the function does this internally). If a block exceeds ~40 lines, split it into labeled parts — cell() does not auto-paginate mid-block.

---

4. FPDF Encoding Limitations

FPDF2 with the default built-in fonts (Helvetica, Courier, Times) uses latin-1 encoding. This means:

Safe: Standard ASCII characters, Western European accented characters (é, ñ, ü, etc.)

Unsafe: Unicode characters beyond latin-1 — Greek letters (α, β), mathematical symbols (∞, ≤), CJK characters, emoji. These will raise errors or render as garbage.

Workarounds:

• Spell out Greek letters in descriptions: "alpha" instead of α
• Use render_formula() for mathematical expressions
• Use \u00a0 (non-breaking space) to preserve indentation in cell() calls
• For Unicode-heavy content, consider using pdf.add_font() with a TTF that covers the needed glyphs, but this adds complexity

---

5. Other Common Pitfalls

Forgetting `matplotlib.use('Agg')`: Must be called before importing pyplot. Without it, matplotlib tries to use a GUI backend that doesn't exist in headless environments, causing crashes.

Forgetting `plt.close()`: Each unclosed figure consumes memory. With many charts, this causes memory issues.

Forgetting `pdf.add_page()`: Content written without a page call won't appear. Always add a page before writing content (the title page method handles this internally).

Using `cell()` for long text: cell() clips text that exceeds the cell width. Use multi_cell() or add_table_wrapped() when text may be long.

Chart images too small or blurry: Use dpi=150 minimum and figsize=(7, 4). Smaller images look pixelated in the PDF.

Not resetting font/color: FPDF carries font and color state forward. After any custom styling (bold, colored text), explicitly reset to body defaults:

pdf.set_font('Helvetica', '', 11)
pdf.set_text_color(*pdf.COLORS['body'])

Filenames with spaces: Use underscores in /tmp/ paths. Some environments have issues with spaces.

Not calling `generate_download_link`: The user can't download without it. Always call it after saving.