Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Use --margin-top (or its short form -T) to reserve space above the page content. Set --header-spacing separately when you need to change the gap between the rendered header and the content. For example:
wkhtmltopdf --margin-top 20mm --header-html header.html --header-spacing 3 input.html output.pdfThe values in that command are a starting configuration, not a universal measurement. Header height, page geometry, CSS, and the exact wkhtmltopdf build determine the correct result, so inspect a PDF generated by the binary installed on your machine.
The two settings you must distinguish
| Option | What it controls | Typical adjustment |
|---|---|---|
--margin-top or -T |
The page’s reserved top margin. In the library API this is margin.top. |
Increase it when content starts too close to the top edge or when a header needs more reserved room. |
--header-spacing |
The distance between the header and the document content. The command-line manual describes this value in millimetres and lists a default of 0. | Increase or decrease the gap without treating it as a replacement for the top margin. |
The wkhtmltopdf usage manual describes the first option as “Set the page top margin” and the second as “Spacing between header and content in mm.” The libwkhtmltox page-settings reference also explains that excessive header spacing can place the header outside the page; adding or correcting the top margin is part of the fix.
Use the right command for your header
HTML header
For a separate HTML document, pass its path with --header-html and reserve enough top margin for the header’s rendered height:
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
wkhtmltopdf
--margin-top 24mm
--header-html header.html
--header-spacing 4
input.html output.pdfKeep the header document’s own layout predictable. The project’s sample header uses a body element with zero border and margin, then positions content in a table. That is an example of header-document styling, not a guaranteed repair for every clipping or placement problem:
<body style="border:0; margin:0" onload="subst()">
<table width="100%">
<tr>
<td class="section"></td>
<td class="page"></td>
</tr>
</table>
</body>Header CSS, line wrapping, images, and table height all contribute to the space the header actually occupies. A margin that works for a one-line header can clip a two-line header or a larger logo.
Text header
You can use the --header-* text options instead of a separate document. wkhtmltopdf documents substitution tokens such as [page], [topage], [webpage], [title], and [doctitle]. Check the help output from your installed build before relying on a token:
wkhtmltopdf --extended-help | lessFor a simple page counter, a command may look like this:
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
wkhtmltopdf
--margin-top 18mm
--header-left "[title]"
--header-right "Page [page] of [topage]"
input.html output.pdfThe available token behavior can vary with the build, especially where patched-Qt features are involved. Treat the installed binary’s own help as authoritative for availability.
A repeatable way to choose the margin
- Measure the header’s rendered height. Open the header HTML in the same environment, account for wrapping and images, and note the largest height it can reach. Do not measure only the nominal CSS line-height.
- Set an initial top margin. Choose a value clearly larger than the header height, then add the clearance you want below the header. Use an explicit unit for
--margin-top, such as20mm. - Set header spacing independently. Use
--header-spacingfor the header-to-content gap. Its documented unit is millimetres; a value of0removes that extra gap, subject to the header and page layout. - Render a representative page. Include the longest title, largest image, and any page-number token. Inspect the first page and a later page because repeating headers can interact differently with content flow.
- Adjust one variable at a time. If the header is clipped at the top, investigate page geometry and header layout. If content overlaps the header, increase the top margin. If the separation alone is wrong, change spacing rather than moving the margin blindly.
There is no single officially prescribed numeric margin for all headers. The project documentation relates the controls, but it does not define a universal value for every header design.
Page geometry changes the result
Margins are measured inside the selected page geometry. A command that fits on A4 portrait can produce a different composition on Letter, landscape, or a custom page size. Keep these settings together when diagnosing a layout:
wkhtmltopdf
--page-size A4
--orientation Portrait
--margin-top 22mm
--header-html header.html
--header-spacing 3
input.html output.pdfIf you change orientation, paper size, zoom, or header CSS, render again rather than assuming the previous margin remains valid. Header images can also load at a different effective size if their intrinsic dimensions or CSS constraints change.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
Symptoms, causes, and fixes
Content overlaps the header
- Increase
--margin-topso the page reserves more top space. - Keep
--header-spacingat the clearance you actually need; spacing alone does not reserve the page’s top margin. - Check for a header that wraps, has an unexpectedly tall table row, or loads an image at its intrinsic size.
The header is outside the PDF or appears clipped
- Reduce an unnecessarily large
--header-spacing. - Provide adequate top margin and render again; the library reference identifies top margin as a correction when excessive spacing pushes the header out of place.
- Inspect the header document’s body margin and border. The project’s zero-margin sample is a useful starting point, but it is not a universal fix.
The header is missing entirely
- Confirm that
--header-htmlpoints to a readable file or that the text options are supported by the installed build. - Use an absolute file path while diagnosing path and working-directory problems.
- Run the command with the same user and environment that will generate production PDFs; local browser access does not prove the converter can read every resource.
The first page looks right but later pages do not
- Check whether the header’s content changes height when substitution values become longer.
- Test a document with enough pages to exercise
[page]and[topage]. - Confirm that the build repeats the header as expected and that page-specific CSS is not changing its dimensions.
Changing the option appears to do nothing
- Check the exact executable with
wkhtmltopdf --versionand inspectwkhtmltopdf --extended-help. - Make sure the option appears before the input and output arguments.
- Delete or rename the old PDF so you are inspecting the newly rendered file, not a cached viewer tab.
Validate the installed build before automating
The command-line manual is published from the project’s master branch and is not pinned to a particular release in the cited page. Distribution packages and builds can differ, including options associated with patched Qt. Capture the version and help output in your deployment notes:
wkhtmltopdf --version
wkhtmltopdf --extended-help > wkhtmltopdf-help.txtUse those outputs to confirm that --header-html, the text-header options, substitution tokens, and the margin settings exist in the binary you will run. When moving from a developer workstation to a container or server, perform a fresh render there and compare the resulting PDF.
Or skip the browser setup
If your actual goal is a clean screenshot or PDF of a public web page rather than control over a local wkhtmltopdf header, ScreenshotNeo provides a one-request capture API. It handles consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; failed loads, blank pages, bot checks, CAPTCHAs, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. It also offers an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
For API parameters and authentication, see the ScreenshotNeo documentation. This cURL request saves a WebP capture:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)And in 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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo supports PNG, JPEG, WebP, and PDF output, plus full-page and element captures, device presets, custom viewports, retina scale, dark mode, custom CSS and JavaScript, clicks, waits, blocked resources, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Every feature is on every plan: 1,000 screenshots per month free with no card, then Starter at $5 for 3,000, Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000, and Business at $249 for 1,000,000; annual billing provides two months free.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
Create a free ScreenshotNeo account to get 1,000 screenshots a month without adding a card.
Operational and cost considerations
Local wkhtmltopdf jobs
Local rendering gives you direct control over HTML, CSS, headers, margins, and output files. It also means you must package the converter, fonts, header assets, and any required network access consistently. For repeatable output, pin the executable version, store the exact command, and retain a small fixture document that exercises the tallest header and the longest page counter.
Remote capture jobs
An API is useful when the source is a reachable URL and you do not want to maintain a browser or converter runtime. Check response status and the service’s page-verdict headers in your application, and choose synchronous or asynchronous capture according to your workload. ScreenshotNeo’s cache TTL, bulk endpoint, signed webhooks, and usage API can reduce repeated work, but they do not replace checking that the returned artifact matches your required format.
FAQ
Frequently Asked Questions
Can I use --header-spacing without setting --margin-top?
You can pass the options independently, but spacing does not reserve the page’s top margin. Set a top margin large enough for the header whenever the header occupies space above the content.
Why should I test more than one page?
Substitution values such as page counts, wrapped titles, and variable header content can change the rendered height. A multi-page fixture exposes problems that a single short page can hide.
Is a value such as 20mm guaranteed to work for every header?
No. The documentation gives the controls, not one universal number. Measure or inspect your header, render with the installed build, and adjust for its actual height and page geometry.
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.
