Page backgrounds

Solid colors

PageBackground paints a fill behind the content of every page - margins included, edge to edge:

doc.PageBackground(b => b.Color("#EEF5FF"));

Any Color works, including a translucent one. Where the format supports real transparency the color composites over white paper; where it does not, it is pre-blended against white (see Per-format behavior).

Gradients

LinearGradient takes an angle and two or more color stops:

doc.PageBackground(b => b.LinearGradient(90f, "#FFFFFF", "#0B3D91"));

The angle is degrees counter-clockwise from the positive x-axis - the same convention as Watermark.Rotation. 0 runs left to right, 90 bottom to top. The ramp spans the page’s bounding box at that angle, so the first stop lands exactly on one corner and the last on the opposite one.

For more than two colors, pass explicit stops with offsets in [0, 1]:

doc.PageBackground(b => b.LinearGradient(
    90f,
    new GradientStop(0f, "#FFFFFF"),
    new GradientStop(0.25f, "#CCE4FF"),
    new GradientStop(1f, "#0B3D91")));

Offsets must not descend, but two stops may share one offset - that is a hard color break rather than a blend. Stops that do not reach 0 or 1 are extended outward, so the ramp always covers the whole page.

All stops must share one opacity. A translucent gradient is fine; a gradient that fades from opaque to transparent is not, and throws when rendering to PDF - a PDF shading has no alpha channel, and faking it would need a soft mask Papyra does not emit.

Images

Image takes the same formats as doc.Image - JPEG and PNG embed as-is, everything else ImageSharp can decode is converted to PNG:

doc.PageBackground(b => b.Image(textureBytes, PageBackgroundFit.Cover));

Fit	Behavior
`COVER` (default)	Scales to cover the page, cropping the overflow. Aspect ratio preserved.
`CONTAIN`	Scales to fit inside the page, centered. Aspect ratio preserved, so a non-matching ratio leaves uncovered bands at the edges - there is no backdrop color to fill them.
`STRETCH`	Stretches to exactly the page size, distorting the aspect ratio.
`TILE`	Repeats at natural size from the top-left corner. One image pixel is one point (72 dpi) in PDF and HTML.

A very small TILE source produces a lot of placements - roughly 200 for a 50×50 px tile on A4 - and each one is a separate draw in the PDF content stream, repeated on every page.

DOCX only supports two of these four. VML fills are either stretched to the shape or tiled, so COVER, CONTAIN, and STRETCH all render as stretch in Word - a CONTAIN background will not letterbox and a COVER background will not crop. TILE tiles, but at the image’s own DPI rather than one pixel per point, so the tiles come out smaller than in PDF and HTML. Use PDF or HTML where the fit mode has to be exact.

Color, gradient, and image are mutually exclusive; setting more than one throws.

Per section

Sections inherit the document’s background, override it with their own, or opt out with an empty callback - the same rule headers and footers use:

doc.PageSize(PageSize.A4)
   .PageBackground(b => b.Color("#EEF5FF"))     // the document default
   .Section(s => s.Paragraph(p => p.Text("Inherits the light blue")))
   .Section(s => s
       .PageBackground(b => b.Color("#FFF8E1"))  // overrides it
       .Paragraph(p => p.Text("Amber")))
   .Section(s => s
       .PageBackground(_ => { })                 // suppresses it - plain white
       .Paragraph(p => p.Text("No background")));

Per-format behavior

PDF - drawn as the first operators of every page’s content stream, so it sits behind the watermark, headers, body, and footers. A gradient becomes a native axial shading (PDF/A-conformant under 2b, 3b, and 4 - veraPDF-verified); a translucent color or gradient is true transparency via an ExtGState. Page geometry is baked into the shading, so the same gradient on two differently sized sections renders correctly on both.
DOCX - a full-page VML rectangle in the header parts, the only per-page repeating container WordprocessingML has; a header part is created even when the document sets no Header(...). This is deliberately not Word’s native w:background, which is document-wide (so per-section backgrounds would be impossible) and which Word does not print unless the reader enables a non-default option. The trade-off: Word’s Page Color UI does not reflect the rectangle, and it appears as a header shape when editing. WordprocessingML has no alpha, so a translucent color is pre-blended against white, and a VML fill is either stretched or tiled - see the fit-mode note above.
XLSX - a worksheet has no page, so the background becomes a sheet fill: every column carries it as a default style and every cell that sets no fill of its own inherits it, so the color covers the whole sheet and prints. A gradient is flattened to its first stop (Excel’s gradient fill is per-cell and would repeat the whole ramp in every cell), and an image background is ignored
- Excel’s sheet picture tiles and never prints.
HTML - a background declaration on the section’s page container, including print-color-adjust: exact so browsers do not drop it when printing. Colors, gradients, and images all map to their native CSS equivalents; the image is embedded as a data: URI. In print, @page owns the margins, so the background covers the printable area rather than bleeding to the sheet edge.