pdf-report-formatting

name: pdf-report-formatting description: Produce branded, professionally formatted PDF reports with selectable themes (light/cyber), cover page, table of contents, running header, page-N-of-M footer, consistent typography, modern tables, callouts, and ordered/unordered lists. Use whenever the user asks for a PDF report, briefing, white paper, audit deliverable, technical memo, or wants existing markdown/text/HTML content turned into a polished PDF — even if they don't explicitly say "PDF formatting". Also use when the user asks for a "tactical", "terminal", "cyber", or "dark mode" PDF, or wants the report to match a specific brand palette. Prefer this skill over generic PDF tools when output style/branding matters.

PDF Report Formatting

Produce consistent, professional PDF reports. Styling lives in scripts/build_pdf.py; per-invocation work is content, not layout.

When to use

Branded reports, audit deliverables, technical memos, briefings, white papers, structured analyses converted to PDF. For raw PDF manipulation (merge, split, extract, OCR), use the generic pdf skill instead.

Workflow

1. Decide the document shape: title, subtitle, optional cover metadata, ordered list of Section objects, each with typed Block children.
2. Read scripts/build_pdf.py once to confirm the API (or rely on the example below).
3. Construct the data structures in a small driver script that imports build_report from scripts/build_pdf.py.
4. Run it. The builder runs a two-pass multiBuild to resolve TOC + page count.
5. Verify visually: cover page renders, TOC page numbers match, no orphaned headings, no Unicode boxes.

The styling lives in the builder. Resist the urge to inline custom Paragraph styles or bespoke TableStyle per call — extend the builder if a new pattern is genuinely reusable.

Tooling

reportlab Platypus is the default. Two-pass multiBuild for TOC + page-N-of-M. Install with pip install reportlab --break-system-packages.

Themes

A Theme is a frozen dataclass holding every visual parameter the builder uses: page background, text colors, accent colors, table styling, callout tints, heading behavior, and optional decorations (corner brackets, footer divider).

Two presets ship with the skill, both registered in THEMES:

Pass via theme="<name>" or theme=Theme(...) for custom. Defaults to "light".

build_report(
    output_path="report.pdf",
    title="Quarterly Risk Review",
    theme="cyber",                    # registered preset
    cover_page=False,                 # cyber looks best with inline title
    table_of_contents=False,          # tactical briefings rarely need TOC
    numbered_sections=False,          # cyber section titles are usually un-numbered
    sections=[...],
)

Layouts

A Layout bundles the structural-element choices (cover page, TOC, section numbering) into a named preset, so you don't have to remember the right combination of three flags every time.

Three presets ship registered in LAYOUTS:

Pass layout="<name>" or layout=Layout(...) for custom. Individual parameters override the layout if explicitly set — so layout="tactical", table_of_contents=True gives you a tactical look but keeps the TOC. This is exactly how navigable_tactical is built internally.

Theme/Layout pairing recommendations:

build_report(
    output_path="briefing.pdf",
    title="Threat Brief — Q1 2026",
    subtitle="Adversary capability assessment",
    metadata={"Classification": "INTERNAL", "Date": "2026-05-07"},
    sections=[...],
    theme="cyber",
    layout="tactical",   # the original strix-halo briefing layout
)

Custom theme:

from build_pdf import Theme, build_report

amber_terminal = Theme(
    name="amber",
    background="#1A0F00",
    text_primary="#FFB000",
    text_secondary="#FFCB47",
    text_muted="#7A5A1F",
    accent="#FFB000",
    title_color="#FFB000",
    subtitle_color="#FF8B00",
    heading_color="#FFB000",
    metadata_label_color="#FFB000",
    metadata_value_color="#FFE5A8",
    table_header_bg="#1A0F00",
    table_header_fg="#FFB000",
    table_header_rule="#FFB000",
    table_body_rule="#3D2A0E",
    table_emph_bg="#2A1B05",
    table_cell_fg="#FFE5A8",
    callout_note_bg="#2A1B05",
    callout_warn_bg="#2A1410",
    callout_border_note="#FFB000",
    callout_border_warn="#FF6B35",
    callout_text="#FFE5A8",
    header_text_color="#7A5A1F",
    header_rule_color="#FFB000",
    footer_text_color="#7A5A1F",
    footer_rule_color="#FFB000",
    footer_rule=True,
    caps_headings=True,
    corner_brackets=True,
    corner_bracket_color="#FFB000",
    toc_heading_color="#FFB000",
    toc_level1_color="#FFE5A8",
    toc_level2_color="#FFCB47",
)

build_report(..., theme=amber_terminal)

Theme caveats:

• Dark themes consume printer ink heavily. Document is screen-first.
• Reportlab's built-in fonts (Helvetica family) ship with full Latin glyphs but no CJK / Cyrillic. If your content has those, embed a font (see references/style_guide.md).
• Callouts use semantic colors (note=cool/blue, warn=warm/orange) regardless of theme. The cyber theme's note border is cyan; warn border is orange — picked for accessibility contrast on the dark background.
• Corner brackets are a decorative element only; they don't enclose content (the body frame is unchanged from non-bracketed themes).
• Themes are frozen dataclasses. To tweak a registered theme, use dataclasses.replace: my_theme = replace(CYBER_THEME, accent="#00FF00").

What the builder produces by default

Page geometry

• Page size: letter (US). Pass page_size=A4 for non-US audiences.
• Margins: 0.6 inch on all sides.
• Header band: 0.3 inch above the body frame on body pages.
• Footer: 0.35 inch from bottom.

Typography contract

Stick with Helvetica/Times/Courier built-ins unless you embed TTFs via pdfmetrics.registerFont(TTFont(...)). Embedded fonts add ~200 KB per face and have licensing implications.

Tables

Modern style: horizontal rules only, no vertical grid lines. Header row gets a tinted fill (#f5f5f5), bold text, and 1pt rules above/below; body rows get 0.25pt separators. repeatRows=1 so the header reappears across page breaks.

Cells are auto-wrapped in Paragraph so they word-wrap inside their column. Pass col_widths to lock dimensions for important tables.

For row emphasis (e.g., a recommended option in a decision matrix), use the emphasized_rows parameter — this triggers both bold text and a tinted background, applied as table style rather than markup so the data stays clean.

TableBlock(
    header=["Option", "F", "A", "I", "Total", "Notes"],
    rows=[
        ["A. Do nothing", "5", "1", "1", "7", "Cheap, brittle."],
        ["B + D parallel", "4", "5", "4", "13–14", "Recommended."],
    ],
    col_widths=[1.6*inch, 0.4*inch, 0.4*inch, 0.5*inch, 0.7*inch, 3.3*inch],
    emphasized_rows=[1],  # second row (0-based, body rows only)
)

Building blocks

Section semantics

A Section(title, blocks, starts_on_new_page=False) is the top-level container. The builder auto-renders the title (with optional numbering) and applies KeepTogether to the title + first block to prevent orphaned headings.

Two driver mistakes the builder will refuse:

1. PageBreakBlock as the first child of a section — caused the v2 PDF's empty page 4. Use Section(starts_on_new_page=True) instead.
2. An H1 HeadingBlock whose text matches the section title — caused the v2 PDF's duplicate "5. MPCoA / MDCoA Table". Section titles render automatically; remove the redundant heading.

Both raise ValueError with a clear message at build time.

Callouts and keep_with_previous

Callouts that qualify a preceding table or paragraph should set keep_with_previous=True. The builder wraps the callout and its anchor in KeepTogether, preventing the callout from floating to the next page alone (the v2 PDF's page-3 orphan). Without this hint, callouts can break across page boundaries.

Gotchas (read before generating)

1. HTML escaping: any user content with &, <, > flowing into Paragraph must be escaped — from xml.sax.saxutils import escape; escape(s). Reportlab raises a parse error or silently drops content otherwise.
2. Em/en dashes: prefer — and – entities inside Paragraph markup.
3. Long table rows: a single row taller than a page raises LayoutError. Break the row content.
4. Image scaling: Image(path, width=w, height=h) does not preserve aspect ratio — compute one dimension from the other.
5. Metadata leakage: title= and author= embed in the file. For sensitive content, set explicitly.
6. No browser storage / no external resources: embed everything; PDFs render offline.
7. Two-pass build is slow for very large docs — ~2x baseline. Disable TOC if you don't need it.

Security notes

• Treat any user-supplied string flowing into Paragraph HTML as untrusted. Escape it.
• If the input is markdown, run it through a markdown→reportlab converter or a sanitizer before passing as Paragraph markup.
• If embedding fonts from assets/, verify the font license permits PDF embedding.
• Vanilla reportlab output is not PDF/A or PDF/UA compliant. For legal/government/accessibility deliverables, post-process with veraPDF + a converter; document this gap to the user.

Verification (run after every build)

1. Confirm pypdf.PdfReader(path).pages yields the expected page count.
2. pdftotext the file and confirm no □ (white square) or � (replacement) characters.
3. Confirm the TOC page numbers match actual section locations.
4. For multi-page tables, confirm the header row repeats on continuation pages.
5. Render page 1 to PNG and confirm the cover layout looks right (title centered, no orphaned content).

References

• scripts/build_pdf.py — the canonical builder.
• references/style_guide.md — palette rationale, additional patterns, error catalogue.

Example driver

from scripts.build_pdf import (
    build_report, Section, HeadingBlock, ParaBlock,
    BulletsBlock, OrderedListBlock, TableBlock, CalloutBlock,
)
from reportlab.lib.units import inch

build_report(
    output_path="/abs/path/out.pdf",
    title="Quarterly Risk Review",
    subtitle="Q1 2026",
    metadata={"Author": "Risk Office", "Classification": "Internal", "Date": "2026-05-07"},
    sections=[
        Section(title="Executive Summary", blocks=[
            ParaBlock("Three open issues, two trending green, one trending red."),
            CalloutBlock(
                "Issue R-12 requires steering-committee decision by 2026-05-30.",
                kind="warn",
                keep_with_previous=True,
            ),
        ]),
        Section(title="Findings", starts_on_new_page=True, blocks=[
            TableBlock(
                header=["ID", "Severity", "Status"],
                rows=[
                    ["R-10", "High", "Mitigated"],
                    ["R-11", "Medium", "In progress"],
                    ["R-12", "Critical", "Open"],
                ],
                emphasized_rows=[2],
            ),
        ]),
        Section(title="Recommendations", blocks=[
            OrderedListBlock([
                "Resolve R-12 before 2026-05-30.",
                "Schedule re-test for R-11 on next sprint boundary.",
                "Close R-10 in the risk register.",
            ]),
        ]),
    ],
)