Free tools Windows power users keep installed
One-click scans. No signup required.
There is no single verified fix for every height: 100% header in wkhtmltopdf 0.12. First separate CSS sizing inside the header HTML from the PDF page layout: add a DOCTYPE to the header document, then test --margin-top and --header-spacing together. The top margin reserves space on the page; header spacing controls the gap between the header and the content. A zero top margin can coincide with a missing header, while excessive spacing can push it outside the PDF.
First identify which “100% header height” problem you have
The phrase can mean two different things. The header’s own HTML or CSS may contain height: 100% and render taller than expected, or the header may occupy too much of the PDF page because of its position relative to the page content. These are separate problems with different controls. The title alone, without the header HTML, command line, build and resulting PDF, cannot identify which one is happening.
- Header is too tall or clipped inside its own area: inspect the header document’s markup, CSS and sizing context.
- Large blank gap above the page content: inspect the page’s top margin and header spacing.
- Header is missing: inspect the top margin, spacing and header document; a reported wkhtmltopdf 0.12.5 case had no visible header with a zero top margin.
- Problem changes between machines or versions: record the exact binary and whether it uses patched Qt before assuming the same settings will behave identically.
A successful fix in one report is a diagnostic lead, not a guarantee for every 0.12 build or every CSS rule.
How top margin and header spacing interact
These are page-level controls, not substitutes for correcting a CSS height in the header document. The wkhtmltopdf usage documentation describes --header-spacing as spacing between the header and content, measured in millimeters. The settings reference warns that spacing set too large can put the header outside the PDF and points to the top margin as a corrective control.
#1 Best Overall
| Control | What it changes | What to check |
|---|---|---|
--margin-top |
Space reserved at the top of the PDF page. | Whether there is enough room for the header to appear without colliding with the document content. |
--header-spacing |
Gap between the header and the content, in millimeters. | Whether the gap is too large and is moving the header outside the page. |
| CSS in the header HTML | The header document’s own layout and element dimensions. | Whether a percentage height has a useful containing block and whether its parent elements, margins or padding affect the rendered area. |
Do not assume that increasing the margin is always the answer. A larger top margin reserves more page space but also moves the content down. Increasing header spacing changes the gap and, if excessive, can make the header disappear beyond the page. Test one value at a time and inspect the PDF after each change.
Reproduce the issue with the same binary and wrapper
Before changing a production template, make a small reproduction that uses the same wkhtmltopdf executable and invocation path as production. If a wrapper or application library builds the command for you, capture the actual command it runs as well as the wrapper’s configuration. Otherwise a local test may not reproduce the build or options that generated the faulty PDF.
- Record the operating system, exact wkhtmltopdf version, full command line, and whether the build uses patched Qt.
- Reduce the input to one page and a small header HTML file, keeping the relevant CSS and header option.
- Save the generated PDF for inspection. Note whether the result is a tall header, a blank gap, clipping, overlap with content, or a header that is absent.
- Change only one page-layout value or one CSS feature per run so the result shows which adjustment mattered.
A reported excess-whitespace issue concerned wkhtmltopdf 0.12.5 with patched Qt and --header-html. Its reported workaround was to set top and bottom margins manually. The issue was assigned a 0.12.7 milestone; that assignment is not proof that all builds behave alike or that the workaround is universal.
Add a DOCTYPE to the header document
Make the header a complete HTML document, rather than a fragment, and include a DOCTYPE as its first line. A project mailing-list discussion reports that adding <!DOCTYPE html> resolved one header-rendering problem. The same discussion says margins and padding still needed adjustment to prevent overlap, so a DOCTYPE is a sensible first check—not a replacement for checking the PDF layout.
Rank #3
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
html, body {
margin: 0;
padding: 0;
}
.header {
/* Keep the header's intended height explicit while diagnosing. */
height: 24px;
}
</style>
</head>
<body>
<div class="header">Document header</div>
</body>
</html>The example uses a fixed height only to make a minimal test easier to inspect; it is not a universal recommended header size. If your actual header must vary in height, keep its real content in the reproduction after the basic case behaves as expected.
Test the command-line layout controls
For a direct CLI reproduction, use the same input and header files, and specify top and bottom margins explicitly. This example uses illustrative values in millimeters; adjust them for the actual header and page content rather than treating them as a prescribed fix.
Rank #4
- Used Book in Good Condition
wkhtmltopdf
--header-html header.html
--margin-top 25
--margin-bottom 15
--header-spacing 3
input.html output.pdfRun the baseline, then vary one value at a time. If the header is absent, test a nonzero top margin. If the header appears but the gap is too large, reduce header spacing. If there is excess whitespace across the page, test explicit top and bottom margins. Check for both header visibility and content overlap; a change that fixes one can expose the other.
- Keep the header document and CSS unchanged while testing a modest nonzero top margin.
- Once the header appears, adjust
--header-spacingin small increments to control the gap. - If the overall page still has excess whitespace, adjust the explicit margins and inspect both the first and subsequent pages.
- Repeat the final command using the production binary and wrapper before adopting the values.
The command is a starting point for isolating the page-level behavior. It does not establish that a particular numeric setting fixes a CSS height: 100% rule.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Best Value
- THE PERFECT GIFT IDEA: The perfect gift can be hard to find, but with this unique, not-sold-in-stores coffee and tea mug, you’re sure to give the best gift every time.
- TREAT YOURSELF OR A FRIEND: Whether you’re buying this high quality mug for yourself, a friend, boss, co-worker, or family member they’re sure to love its distinctive, long-lasting design. It’s a great, multi-functional gift for anyone for any occasion.
- PREMIUM QUALITY: Our premium, full-color sublimation imprint appears on both sides of this 11 ounce, white ceramic mug. Each mug is crafted from the highest grade ceramic, and all of our designs are printed and sublimated in the United States.
- MICROWAVE AND DISHWASHER SAFE: This 11 ounce, white ceramic coffee mug has a large, easy-to-grip C-handle and is both microwave and dishwasher safe.
- SATISFACTION GUARANTEED:Your complete satisfaction is our top priority. We meticulously package our mugs to ensure they arrive on time and in great condition.
Diagnose CSS height: 100% separately
If the header itself is oversized, temporarily replace the percentage height with a small explicit height in the minimal reproduction. If that changes the result, the CSS sizing context is relevant; if it does not, return to the page-level layout checks. A percentage height depends on the dimensions available from its containing context, and the header document may not receive the dimensions your stylesheet assumes. Inspect the computed relationship between the header element and its parent elements instead of trying arbitrary percentage values.
- Check whether the header HTML contains a DOCTYPE and is a complete document.
- Inspect margins and padding on the document, body and header elements; they can add space or create overlap.
- Test with the header’s content reduced to a short line, then restore images and other elements one at a time.
- Do not infer that page size or content height automatically defines the containing block for a header document.
The reviewed project reports do not establish a universal CSS declaration that fixes every height: 100% header. Keep the conclusion tied to the reproduction you actually test.
Common symptoms and next checks
| Symptom | Likely area to investigate | Next check |
|---|---|---|
| Header not visible when top margin is zero | Reserved page space | Test a nonzero --margin-top; one 0.12.5 report describes a missing header with a zero top margin. |
| Header seems pushed off the page | Header spacing and top margin | Reduce --header-spacing and verify the top margin; the settings reference warns about excessive spacing. |
Large whitespace with --header-html |
Build-specific page margins | Test explicit top and bottom margins in the same 0.12.5 patched-Qt environment if that is your build. |
| Header content overlaps or renders oddly | Header HTML document structure and CSS spacing | Add a DOCTYPE, then inspect margins and padding in the header document. |
| Only the percentage-height header is wrong | CSS sizing context | Compare a minimal fixed-height version with the percentage-height version; do not presume a universal fix. |
Version and build details matter
The wkhtmltopdf downloads page identifies 0.12.6 as the stable series and gives June 11, 2020 as its release date. That is the page’s stated release information, not a recommendation that 0.12.6 is the right build for every environment. The issue reports cited above concern specific 0.12.5 circumstances, including patched Qt in the excess-whitespace report. Preserve the exact build details when comparing results; a version number alone may not identify all relevant differences.
Or skip the browser setup
If your goal is to capture a website page rather than repair a wkhtmltopdf header template, ScreenshotNeo is a website screenshot API and MCP server that can return an image or PDF. It is an alternative capture workflow, not a fix for wkhtmltopdf’s header CSS or margin behavior. One GET request can capture a URL:
Quick Recap
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 options. Cookie banners, popups and chat widgets are removed before the shot; bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
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.
