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 →If wkhtmltopdf creates the PDF but your header is empty, fix it in this order: make the header a standalone HTML document, pass the exact file or URL to --header-html, reserve room with --margin-top, and then tune --header-spacing. A missing header is usually either a loading failure or a page-geometry problem, not a CSS mystery.
What a working wkhtmltopdf header requires
The --header-html option loads an external HTML document and renders it above each page. The header is separate from the document supplied as the main input, so putting a header element in the body HTML does not configure a wkhtmltopdf header.
- A loadable resource: the path or URL must be correct, readable by the conversion process, and permitted by the local-file policy.
- A complete document: use a doctype,
<html>,<head>, and<body>, even for a one-line header. - Reserved page space: the top margin must be taller than the rendered header.
- Reasonable spacing:
--header-spacingadds a gap between the header and body; excessive spacing can move the header outside the printable area.
wkhtmltopdf can also provide page metadata to the header through query-string replacement. Common values include [page], [topage], [sitepage], and [doctitle]. Add dynamic substitution only after static text is visible.
Start with a minimal, standalone header
1. Create header.html
Save this file separately from the report you are converting:
#1 Best Overall
![MixPad Free Multitrack Recording Studio and Music Mixing Software [Download]](https://m.media-amazon.com/images/I/71ltIxIuz1L._SL160_.jpg)
- Create a mix using audio, music and voice tracks and recordings.
- Customize your tracks with amazing effects and helpful editing tools.
- Use tools like the Beat Maker and Midi Creator.
- Work efficiently by using Bookmarks and tools like Effect Chain, which allow you to apply multiple effects at a time
- Use one of the many other NCH multimedia applications that are integrated with MixPad.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Header</title>
<style>
html, body { margin: 0; padding: 0; }
body { font: 10pt Arial, sans-serif; color: #222; }
.header { border-bottom: 1px solid #999; padding: 0 0 3mm 0; }
</style>
</head>
<body>
<div class="header">Test header</div>
</body>
</html>The doctype is important to try when a header is skipped or laid out unexpectedly. A named wkhtmltopdf support report specifically recommends a doctype, although behavior can vary by build.
2. Convert with an explicit top margin
wkhtmltopdf
--margin-top 25mm
--header-spacing 3
--header-html /absolute/path/header.html
input.html output.pdfReplace the path with the real location. On Windows, quote paths containing spaces:
wkhtmltopdf --margin-top 25mm --header-spacing 3 --header-html "C:reportsheader.html" "C:reportsinput.html" "C:reportsoutput.pdf"Open the PDF and confirm that “Test header” appears on every page. If it does not, do not change fonts or complex CSS yet; diagnose loading first.
Separate loading failures from layout failures
When the header never appears
A completely absent header usually means wkhtmltopdf could not load the external document. Check the command’s standard error output for messages such as “Failed loading page” or an HTTP error. Some builds continue converting the main document after skipping a failed header, which makes the result look like a rendering bug.
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 problems- Use an absolute filesystem path rather than a relative path.
- Confirm the file exists and is readable by the user account running wkhtmltopdf.
- For a URL, test that URL in the same machine and network environment as the conversion process.
- If you use a file URL, format it as a valid
file:///URL and quote it correctly for the shell. - On builds that restrict local resources, enable local-file access only when appropriate for your input and header assets. Keep the setting consistent for CSS, images, and other local files.
Run the header as an independent input when possible. A standalone test can reveal malformed HTML, a missing stylesheet, or a permissions error without the rest of the report obscuring the cause.
When the header exists but is clipped or overlaps content
This is a page-geometry problem. The header is rendered into the top margin; a zero or undersized --margin-top can make a correctly loaded header invisible behind the body. Increase the margin to at least the header’s actual height, including borders and padding.
--header-spacing is the gap after the header. Start with a small value such as 3. If the header is pushed off the page or creates surprising blank space, reduce spacing before changing the header’s CSS. If body text begins underneath the header, increase the top margin or reduce the header’s height.
For example, a 12 mm header with 3 mm of separation needs more than 15 mm of top margin. Add a safety allowance for font metrics and borders, then reduce it gradually once the layout is stable.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Use a complete header document before adding dynamic values
Header HTML runs in its own page context. External stylesheets, relative image paths, JavaScript, and web fonts can therefore fail even when they work in the main document. For the first successful test, keep CSS inline and use static text.
Once that works, add page metadata with a small replacement script. wkhtmltopdf appends values to the header request’s query string; the script reads those values and inserts them into elements. This example uses data attributes so the mapping is explicit:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Header</title>
<style>
html, body { margin: 0; padding: 0; }
body { font: 9pt Arial, sans-serif; }
.header { display: flex; justify-content: space-between; border-bottom: 1px solid #888; padding-bottom: 2mm; }
</style>
<script>
function substituteWkhtmltopdfValues() {
var params = new URLSearchParams(window.location.search);
['page', 'topage', 'sitepage', 'doctitle'].forEach(function (name) {
document.querySelectorAll('[data-wkhtmltopdf="' + name + '"]').forEach(function (node) {
node.textContent = params.get(name) || '';
});
});
}
</script>
</head>
<body onload="substituteWkhtmltopdfValues()">
<div class="header">
<span data-wkhtmltopdf="doctitle"></span>
<span>Page <span data-wkhtmltopdf="page"></span> of <span data-wkhtmltopdf="topage"></span></span>
</div>
</body>
</html>Variable availability and JavaScript behavior differ between historical wkhtmltopdf versions and operating-system packages. If static text works but a value is blank, inspect the query string and test one variable at a time. Do not use dynamic substitution as the first diagnostic.
Check paths, URLs, and local-resource policy
Absolute paths and quoting
Relative paths are resolved from the process’s working directory, which may not be the directory containing your report. An absolute path removes that ambiguity. Quote paths with spaces, parentheses, or shell metacharacters.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
![Free Fling File Transfer Software for Windows [PC Download]](https://m.media-amazon.com/images/I/41Vq6ZqHfjL._SL160_.jpg)
- Intuitive interface of a conventional FTP client
- Easy and Reliable FTP Site Maintenance.
- FTP Automation and Synchronization
File URLs
A local header can be supplied as a filesystem path or a URL. If you choose a URL, use the correct number of slashes and URL-encode characters that are not valid in a URL. A malformed file:/// value can produce a loading warning while the main PDF still succeeds.
Permissions and sandboxing
The account launching wkhtmltopdf needs read access to the header and any assets it references. A service account, container, scheduled task, and interactive shell may have different permissions. Test under the same account and working directory used in production.
Some packages restrict local file access for security. If your header references local images or CSS, apply the package’s local-file-access option deliberately, and avoid granting access to directories that contain secrets. A header that contains only inline HTML and CSS is easier to make portable.
Inspect the rendered geometry systematically
- Make the header visibly obvious. Use a solid border and large temporary text such as “TEST HEADER.”
- Set a generous margin. Try
--margin-top 30mmand--header-spacing 2to establish that the header has room. - Measure the actual header. Remove unnecessary padding, large line heights, and fixed heights that exceed the available space.
- Reduce the margin gradually. Keep a small allowance for font rendering and borders.
- Check the body separately. Body CSS with negative margins, transforms, or positioned elements can cover the header area even when wkhtmltopdf placed the header correctly.
Excess whitespace after adding a header is normally corrected by setting margins and padding intentionally in both documents, rather than by removing the header option.
Common symptoms and fixes
| Symptom | Likely stage | Fix |
|---|---|---|
| No header and a loading warning | File or URL loading | Correct the absolute path or URL, verify permissions, and test local-file access. |
| No header but conversion exits successfully | Header skipped after load failure | Read stderr; run the header independently; remove relative asset references. |
| Header text is behind the body | Insufficient top margin | Increase --margin-top to exceed the rendered header height. |
| Header is clipped or appears outside the page | Spacing and page geometry | Reduce --header-spacing and verify the top margin and paper size. |
| Large blank band above the body | Oversized margin or spacing | Reduce spacing first, then trim margin and header padding together. |
| Static text works, page number is blank | Replacement script or variable mismatch | Check the query-string names, JavaScript execution, and the specific wkhtmltopdf build. |
| Header works on one machine only | Environment difference | Record the exact version, package, operating system, account, working directory, and local-file policy. |
Version and environment checks
Behavior has been reported with wkhtmltopdf 0.12.0 and 0.12.5 on both Windows and Ubuntu, so a command that works on one installation is not proof that every build handles headers identically. Capture the exact output of wkhtmltopdf --version along with the command line when diagnosing a deployment issue.
Keep a minimal regression fixture: one main HTML file, one standalone header, inline CSS, and a known output PDF. Once that fixture works, reintroduce external images, stylesheets, JavaScript, and dynamic values one at a time. This identifies whether a later change broke loading or layout.
Rank #4
![WavePad Audio Editing Software - Professional Audio and Music Editor for Anyone [Download]](https://m.media-amazon.com/images/I/B1fcLEGCs6S.png._SL160_.png)
- Full-featured professional audio and music editor that lets you record and edit music, voice and other audio recordings
- Add effects like echo, amplification, noise reduction, normalize, equalizer, envelope, reverb, echo, reverse and more
- Supports all popular audio formats including, wav, mp3, vox, gsm, wma, real audio, au, aif, flac, ogg and more
- Sound editing functions include cut, copy, paste, delete, insert, silence, auto-trim and more
- Integrated VST plugin support gives professionals access to thousands of additional tools and effects
Performance, reliability, and operating cost
A small local header adds little rendering work; remote stylesheets, images, fonts, and scripts add network latency and new failure points. Inline critical header CSS and keep the header independent of resources that can time out. If the main document is generated in a worker, ensure the header remains available for the entire conversion rather than being written to a temporary path that is deleted early.
Reliability improves when every conversion logs the wkhtmltopdf version, input paths, stderr, exit status, and output size. A successful process exit alone does not prove the header loaded. For local execution there is no per-page API charge, but CPU, memory, storage, and the time spent retrying failed resource loads still affect operating cost.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Or skip the browser setup
If your goal is a clean image or PDF of a web page rather than a wkhtmltopdf-specific document, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server lets Claude, Cursor, or another MCP client call take_screenshot, get_page_info, and capture_pdf.
Use the documented API options for full-page captures, CSS-selector elements, device presets, retina scale, PDF paper and margins, custom CSS or JavaScript, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous webhooks, bulk capture, and usage reporting.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for request parameters. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account to try it.
FAQ
Can I put the header markup in the main HTML file?
Not when using --header-html. That option expects a separate external HTML document. Keep the report body and header in separate files.
Free tools Windows power users keep installed
One-click scans. No signup required.
Why does increasing the top margin make the header appear?
wkhtmltopdf lays the header in the reserved top margin. With no room, the header can be clipped, covered, or effectively invisible even though it loaded correctly.
Best Value
![MixPad Multitrack Recording Software for Sound Mixing and Music Production Free [Mac Download]](https://m.media-amazon.com/images/I/51kaO82jYOL._SL160_.jpg)
- Mix an audio, music and voice tracks
- Record single or multiple tracks simultaneously
- Intuitive tools to split, trim, join, and many other editing features
- Loaded with audio effects including EQ, compression, reverb, and more.
- Load an audio file and export to all popular audio formats from studio quality wav to high compression formats
Should I add JavaScript immediately for page numbers?
No. Prove that static header text loads first. Then add the documented query-string replacement script and one variable at a time.
What should I preserve when reporting a bug?
Include the exact wkhtmltopdf version, operating system, package source, command, header path or URL, stderr warnings, and a minimal pair of HTML files that reproduces the result.
Frequently Asked Questions
Can I put the header markup in the main HTML file?
Not when using --header-html; that option loads a separate external HTML document.
Why does increasing the top margin make the header appear?
The header is laid out in the reserved top margin, so an undersized margin can clip or hide it.
Should I add JavaScript immediately for page numbers?
First verify static text, then add the query-string replacement script and variables incrementally.
What should I preserve when reporting a bug?
Record the exact version, operating system, package, command, header path or URL, stderr, and minimal reproducible files.
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.
