ScreenshotNeo

BlogHow-to

How to Add a Header to Every Page in wkhtmltopdf

Add a repeating page header in wkhtmltopdf with text or custom HTML, page numbers, and margins that keep the header clear of your content.

By the ScreenshotNeo team30 September 20269 min read

How to Add a Header to Every Page in wkhtmltopdf

To add a running header to every page in wkhtmltopdf, use its page-header options. For a short text header with page numbers, run:

wkhtmltopdf --header-left "Quarterly report" --header-right "Page [page] of [topage]" --margin-top 20mm input.html output.pdf

Use --header-html when you need a designed header with multiple elements or dynamic fields. Set --margin-top large enough to make room for the header, and adjust --header-spacing to control the gap between the header and the document content. The official wkhtmltopdf usage manual documents these options.

A page header is different from an HTML table heading. A page header runs at the top of each PDF page; a table’s <thead> belongs to that table and may repeat when the table crosses a page boundary.

1. Choose the kind of header you need

First decide whether the repeated content belongs to the page or to a table.

Need Use Typical content
Same label on each PDF page --header-left, --header-center, or --header-right Report name, date, page count
Styled or multi-part running header --header-html Section label, rule, page numbering
Column labels repeated within a long table HTML table <thead> Column names at table page breaks

The manual describes page headers as options supplied to wkhtmltopdf. It lists plain text positions, font settings, a header line, and an HTML header document. Pick the simplest option that meets the layout requirement: text switches are easy to configure; HTML gives you more control over structure and styling.

2. Add a plain text header

Pass one or more header position options and include enough top margin for the header and its separation from the body:

wkhtmltopdf \
  --header-left "Acme / Operations" \
  --header-center "Monthly report" \
  --header-right "Page [page] of [topage]" \
  --header-font-name "Arial" \
  --header-font-size 9 \
  --header-line \
  --header-spacing 4 \
  --margin-top 22mm \
  input.html output.pdf

This example uses the documented page variables [page] for the current page and [topage] for the final page count. The manual also lists variables such as [title] and [doctitle]. Header spacing is specified in millimeters; the documented default is 0, and the header font size default is 12. Defaults describe behavior, not a good fit for every design.

For a minimal header, omit the options you do not need:

wkhtmltopdf \
  --header-right "Page [page] of [topage]" \
  --margin-top 18mm \
  input.html output.pdf

Keep the text concise. A long header can wrap or compete with page content, and a larger font needs more vertical room. After changing font size or adding a header line, render and inspect several pages, including the first and last.

3. Build a custom HTML header

For a logo-free branded layout, multiple aligned fields, or other custom markup, create an HTML file and pass its path or URL through --header-html. The manual’s example uses the header document’s query string to supply replacement values and elements with matching CSS classes to display them.

A small header document can look like this:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    body { margin: 0; font: 9pt Arial, sans-serif; color: #333; }
    .row { display: flex; justify-content: space-between; border-bottom: 1px solid #999; padding-bottom: 4px; }
  </style>
</head>
<body>
  <div class="row">
    <span class="section"></span>
    <span>Page <span class="page"></span> of <span class="topage"></span></span>
  </div>
  <script>
    function params() {
      return new URLSearchParams(window.location.search);
    }
    const p = params();
    document.querySelector('.section').textContent = p.get('section') || 'Report';
    document.querySelector('.page').textContent = p.get('page') || '';
    document.querySelector('.topage').textContent = p.get('topage') || '';
  </script>
</body>
</html>

When using the wkhtmltopdf replacement-variable pattern, check the manual’s exact example for your build and use its expected class/query-string convention. The page and header are rendered separately, so a header document must be accessible to the wkhtmltopdf process. For example, a local path that works on your laptop may not exist inside a container or on the server running the conversion.

Invoke the custom header along with suitable spacing and top margin:

wkhtmltopdf \
  --header-html header.html \
  --header-spacing 4 \
  --margin-top 24mm \
  input.html output.pdf

If the header needs values such as a section name or title, follow the manual’s query-string substitution approach rather than assuming the document’s JavaScript can inspect the main page’s DOM. Keep external assets and stylesheets reachable from the rendering environment.

4. Set margins and spacing deliberately

--margin-top reserves space at the top of the PDF page. --header-spacing sets the distance between the header and the body content, in millimeters. They solve related but distinct layout problems: margin creates page space; spacing separates the header from the content within that space.

The top margin reserves room for the running header, while header spacing separates it from the body.
The top margin reserves room for the running header, while header spacing separates it from the body.
  1. Start with a top margin that is visibly larger than the header’s height.
  2. Set a modest spacing value, such as a few millimeters, if content sits too close to the header.
  3. Render the PDF and inspect whether the header, body, and any header rule fit without collision.
  4. Increase the top margin if the header overlaps content or appears clipped; reduce spacing if the header is pushed outside the page area.

The manual warns that excessive header spacing can put the header outside the PDF page. A large spacing value is not a substitute for a thoughtful margin. Measure based on the actual rendered header, including font size, line height, and any border or padding.

5. Keep a table heading separate

If by “header on every page” you mean repeating column labels for a multi-page table, use table markup. A page-level --header-* option repeats content at the top of the page; it does not create a table’s column heading. A table heading can be represented with <thead>:

A page header and a repeated table heading serve different scopes and use different mechanisms.
A page header and a repeated table heading serve different scopes and use different mechanisms.
<table>
  <thead>
    <tr><th>Name</th><th>Status</th><th>Updated</th></tr>
  </thead>
  <tbody>
    <tr><td>Example item</td><td>Ready</td><td>2026-09-30</td></tr>
  </tbody>
</table>

Validate table pagination in the generated PDF when the repeated heading matters. Historical reports in the project issue tracker describe table-header overlap and awkward breaks in particular documents and versions; they do not prove that every build or table will fail. See issue #3737 and issue #2182.

6. Use the options in the right place

wkhtmltopdf accepts global options and page options. The manual explains that page options can be associated with the page being rendered, so check how your command or wrapper groups arguments. A reliable starting point for a single input file is to put the header and margin switches on the same command invocation that converts that input.

For a multi-object command that combines several pages or documents, consult the usage manual and the wrapper’s documentation to confirm which options apply globally and which apply to a particular page object. If a header appears on only some pages, inspect option placement and object boundaries before changing the HTML.

7. Troubleshoot common problems

Symptom Likely cause What to do
No header appears Options were omitted, misspelled, or applied to a different page object. Check the exact command and option grouping. Confirm the header option reaches the page being rendered.
Header overlaps the first body line Top margin is too small for header height and spacing. Increase --margin-top, then render again and inspect the affected page.
Header is clipped or outside the page Header spacing or header content consumes too much vertical room. Reduce --header-spacing or header height. The manual cautions that excessive spacing can push the header outside the page.
HTML header is blank The renderer cannot load the header path or URL, or dynamic replacement values are not set up as expected. Check file accessibility from the conversion process, including container paths and network access. Follow the manual’s query-string and class convention for variables.
Page count or number is missing The replacement variable is absent or spelled incorrectly in the header string/document. Use documented forms such as [page] and [topage] in a text header and verify the HTML-header substitution pattern.
Table heading overlaps rows at a page break This is table pagination behavior rather than the page header option. Inspect the table markup and output around the break. Reproduce with the actual build and document; historical issue reports are document-specific.
Works locally but fails in deployment Different executable/build, unavailable local files, or different wrapper option handling. Check wkhtmltopdf -H in the deployment environment and verify file paths and option placement there.

The project documentation page notes that its documentation is auto-generated and corresponds to wkhtmltopdf -H. The project repository is archived, so verify options against the executable and wrapper you actually use rather than assuming all environments behave alike. See the documentation page.

8. Performance, reliability, and cost

A page header is a layout setting; it does not by itself make conversion faster or slower in a predictable way. A custom HTML header can require additional files or resources to load, so keeping it self-contained and its assets available avoids an avoidable source of rendering failure. For reliable output, pin down the wkhtmltopdf executable available to your runtime, keep the input and header paths valid in that runtime, and inspect representative output after changes.

The research sources provide no benchmark, uptime figure, or cost comparison for this use case. Treat conversion time and operational cost as environment-dependent. If PDF generation is part of a service, account for the conversion process, input page complexity, and operational needs in your own measurements rather than relying on a generic speed claim.

9. Create a repeatable validation checklist

  • Decide whether the requirement is a page-level header or a repeating table heading.
  • Confirm your installed build exposes the options you plan to use with wkhtmltopdf -H.
  • Use --header-left, --header-center, or --header-right for short text; use --header-html for custom structure.
  • Set --margin-top and --header-spacing based on the rendered design.
  • Check page variables, HTML header accessibility, and dynamic field substitution.
  • Inspect the first, middle, and last pages, plus table breaks if tables are involved.
  • Repeat the check in the same container, server, or wrapper used for production.

10. Or skip the browser setup

If the job is to capture a web page as an image or PDF, ScreenshotNeo offers a one-call screenshot API. The DIY wkhtmltopdf commands above remain useful when you need wkhtmltopdf’s specific conversion behavior; ScreenshotNeo is an alternative when you want a hosted website capture.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers tell you the page verdict and billing status. Its MCP server provides screenshot tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Learn more at ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.

Frequently asked questions

Can I put the page title in the header?

The manual lists title-related replacement variables, including [title] and [doctitle]. Use the documented variable form and confirm it resolves in your build.

What units does header spacing use?

--header-spacing is in millimeters. The manual documents a default of 0.

Does a page header replace a table’s repeated column headings?

No. A page header is configured with wkhtmltopdf’s header options; a table heading is part of the table’s HTML and its pagination behavior.

Where can I confirm supported options?

Check wkhtmltopdf -H for the installed executable and the project’s usage manual. The documentation site says its generated documentation matches that help output.