Use the PDF renderer’s header feature, not an HTML setting that you expect every renderer to understand. In Puppeteer, enable displayHeaderFooter, set a headerTemplate, and reserve enough top margin for it. Puppeteer renders PDFs using print CSS by default, so check your print styles as well as the header options.
First identify which renderer creates the PDF
HTML does not have one universal instruction for putting a repeating header in a PDF. Your application’s renderer controls how the document is paginated and how content is placed in page margins. Puppeteer, wkhtmltopdf, Prince, and WeasyPrint use different APIs or CSS mechanisms; a setting for one should not be assumed to work in another.
Check the code path that actually produces the file. A framework, reporting library, or hosted service may wrap a renderer, so the relevant configuration could be in a wrapper rather than beside the HTML. Identify the installed renderer and version before changing the implementation, then use that renderer’s documentation for its supported options.
- For Puppeteer, the PDF options include header and footer templates, an enable switch, page-number template classes, and margins.
- wkhtmltopdf documents command-line header/footer settings, HTML header/footer documents, and replacement placeholders.
- Prince uses CSS paged-media page-margin boxes and generated content.
- WeasyPrint supports running elements placed into page margins; its API reference notes a limitation involving the
startparameter ofelement().
Choose based on the renderer already in your application, whether the header is fixed or drawn from document content, whether you need page counters or page-specific layout, and whether the implementation should be configured through an API or CSS paged-media rules. There is no universally best renderer established by these feature differences.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
- 1 ream (500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Add a repeating header with Puppeteer
Set displayHeaderFooter: true and provide the header markup in headerTemplate. Use footerTemplate if you also want a footer, such as page numbering. Reserve space with the PDF margin option: the header occupies the page margin, not the body’s normal content area.
Complete Node.js example
This example loads a page and writes a PDF with a centered report title and a page counter. Replace the example URL and title with your own. The 60px top and 40px bottom margins are illustrative values, not universal settings; adjust them to the actual header, footer, page size, and body layout.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.pdf({
path: 'output.pdf',
displayHeaderFooter: true,
headerTemplate: '<div style="font-size:9px; width:100%; text-align:center;">Quarterly report</div>',
footerTemplate: '<div style="font-size:9px; width:100%; text-align:center;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
margin: { top: '60px', bottom: '40px' }
});
} finally {
await browser.close();
}
})();Run the script in a project where Puppeteer is installed. The essential header-specific settings are displayHeaderFooter, headerTemplate, and the top margin. The footer is optional. Puppeteer’s documented template classes include pageNumber and totalPages; use them in the footer when you want “Page N of M” rather than a static label.
Put the right content in the template
Header and footer templates are HTML snippets. Keep them small and style them explicitly, as in the example, rather than relying on the page’s normal layout styles. This makes the intended alignment and typography clear in the PDF template itself. Decide whether the header is static—such as a report name—or should vary by page. The Puppeteer options establish the template mechanism and page counter placeholders; they do not make a static title automatically derive from arbitrary page content.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #2
- HP Papers is sourced from renewable forest resources and has achieved production with 0% deforestation in North America. Each ream is wrapped in a polyurethane coated paper wrapper to protect the cut sheets from moisture damage
- Sheet size – 8.5 x 11; Thickness – 20 pounds; Brightness – 92 bright white
- HP Copy&Print20 20 pounds printer paper is Forest Stewardship Council (FSC) certified and contributes toward satisfying credit MR1 under LEED (Leadership in Energy and Environmental Design)
- All HP Papers provide premium performance on HP equipment, as well as on all other printer and copier equipment; 100% satisfaction guaranteed; ColorLok technology provides more vivid colors, bolder blacks and faster drying
- Superior quality, reliability, and dependability for high-volume printing at home, at school and in the office; HP Copy&Print20 print and copy paper prevents yellowing over time to ensure a long-lasting appearance for added archival quality
If you need a header on every page, confirm it is in the PDF header template rather than simply placed at the top of the source document. Ordinary document content at the top is part of the body flow; it is not the same configuration as a repeating page header.
Allow enough margin
Set the top margin high enough that body content does not collide with the header, and set a suitable bottom margin if using a footer. There is no single correct margin value: it depends on the header’s height, the chosen page format, and the content layout. Generate the actual PDF and inspect it; increase the reserved margin if the body begins too close to the header or overlaps it.
Check CSS media and page layout
Puppeteer generates PDFs using the print CSS media type by default. A page that looks correct in a browser window can therefore render differently in the PDF if it has print-specific rules or @page styling. Review those rules alongside the PDF options when diagnosing a misplaced header or unexpected body layout.
If the intended output specifically depends on screen styling, Puppeteer documents switching the page to screen media before calling page.pdf():
Recommended Free Tools
Rank #3
- 3 ream case (1,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
await page.emulateMediaType('screen');
await page.pdf({
path: 'output.pdf',
displayHeaderFooter: true,
headerTemplate: '<div style="font-size:9px; width:100%; text-align:center;">Quarterly report</div>',
margin: { top: '60px' }
});Use this only when screen media is the desired source for the PDF’s styling. It does not replace the header options or the need to inspect page margins.
Use the mechanism for your renderer
| Renderer | Header approach | Check before implementing |
|---|---|---|
| Puppeteer | displayHeaderFooter, headerTemplate, optional footerTemplate, page-number classes, and PDF margins. |
PDF output uses print media by default; check print CSS and margin space. |
| wkhtmltopdf | Command-line header/footer options, HTML header/footer documents, and replacement placeholders. | Consult the usage documentation for the installed build; Puppeteer template classes are not portable settings. |
| Prince | CSS paged-media page-margin boxes and generated content. | Use its paged-media approach when the layout calls for CSS-driven running headers, page numbers, or content-derived strings. |
| WeasyPrint | Running elements can place HTML boxes in page margins. | Check the installed release’s compatibility, including the documented limitation on element()’s start parameter. |
These are renderer-specific routes, not interchangeable HTML attributes. If a header option appears to do nothing, verify that your application is invoking the renderer you think it is and that the option reaches its PDF call or command.
Validate the generated PDF
- Confirm the generating package and version. Follow the actual PDF-generation path, including any framework wrapper, and make sure you are configuring the renderer that creates the file.
- Confirm the header is enabled and supplied. In Puppeteer, check that the PDF call contains both
displayHeaderFooter: trueand the intendedheaderTemplate. - Review print layout. Check print CSS and
@pagerules, since Puppeteer uses print media by default. If you intentionally want screen styles, emulate screen media before PDF generation. - Inspect more than the first page. Check the first page and a later page, page breaks, long titles, and page-number formatting. A header can appear correct initially but collide with body content after pagination.
- Adjust margin from the rendered result. Tune the page margin for the real header dimensions and page format, then generate and inspect the PDF again.
Troubleshooting common header problems
The header does not appear
For Puppeteer, first check that displayHeaderFooter is enabled and that headerTemplate is included in the same PDF-generation call. If your application uses another renderer, verify its own header mechanism instead of copying Puppeteer options into it. Also confirm the code you changed is the path that actually produces the PDF.
The body overlaps the header
The page has not reserved enough space for the header, or the chosen page layout differs from the one used when estimating that space. Increase the top margin to suit the rendered header and page format, regenerate the PDF, and inspect the result. Do not treat the example’s 60px value as a guaranteed fit.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsRank #4
- 5 ream case (2,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
The PDF’s styling differs from the browser view
Puppeteer defaults to print media for PDF generation. Inspect print CSS and any @page rules. If the design intentionally relies on screen media, call page.emulateMediaType('screen') before page.pdf().
Page numbers are missing or show the wrong values
In Puppeteer, put the documented template classes such as pageNumber and totalPages in the header or footer template where the counters should render. Check the resulting PDF on both the first and a later page, and make sure the footer has enough reserved bottom margin.
The same setting behaves differently after a dependency change
Check which renderer version is installed and consult its documentation. The available feature information establishes renderer-specific APIs and a WeasyPrint limitation, but does not establish identical behavior across every release or wrapper. Test the generated file with the version your application deploys.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is to capture a page rather than build a custom, repeating PDF header, ScreenshotNeo can return a website screenshot with one GET request. The following is the supplied cURL example; it saves a WebP screenshot, not a PDF configured with a custom header.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- Made in USA: HP Papers is sourced from renewable forest resources and has achieved production with 0% deforestation in North America.
- Optimized for HP technology: All HP Papers provide premium performance on HP equipment, as well as on all other printer and copier equipment.
- Perfect everyday office paper: Superior quality, reliability, and dependability for high-volume printing at home, at school and in the office. Perfect for everyday black and white printing.
- Certified sustainable: HP Office20 20lb printer paper is Forest Stewardship Council (FSC) certified and contributes toward satisfying credit MR1 under LEED (Leadership in Energy and Environmental Design).
- ColorLok technology printing paper: ColorLok technology provides more vivid colors, bolder blacks and faster drying.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request details. ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. The API’s described PDF options include paper size, margins, landscape, and page ranges, but do not establish a custom repeating-header setting, so use your renderer’s header mechanism when that is required.
Sign up for ScreenshotNeo to get 1,000 screenshots a month free with no card.
FAQ
Do I need to add the header to the HTML body?
Not for a repeating Puppeteer page header. Supply it through the PDF header template; body content and the page-margin header are separate parts of the PDF layout.
Is one margin value right for every PDF?
No. Choose space based on the header dimensions and page format, then inspect the generated file for collisions.
Can I use Puppeteer’s header options in wkhtmltopdf or Prince?
No portable setting is established. Configure each renderer with its documented mechanism: wkhtmltopdf header/footer options or Prince paged-media rules.
Frequently Asked Questions
Does a header template automatically repeat text found at the top of my HTML?
No. For Puppeteer, put the desired header markup in the PDF header template; ordinary body content is not the same as a repeating page header.
Can I set one margin value for all page sizes and headers?
No. Reserve space for the actual header and page format, then inspect the generated PDF for collisions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
