How to Fix Huge Margins When Exporting HTML to PDF with Pandoc

Huge margins usually mean Pandoc is using a different PDF engine or intermediate format than you expect. First check the command for --pdf-engine and whether the conversion goes through HTML. With the current HTML route, WeasyPrint uses CSS @page margins; Pandoc’s HTML margin-left, margin-right, margin-top, and margin-bottom variables set body padding instead. That distinction can create wide blank edges. If the route is wkhtmltopdf, those variables are page-margin settings instead.

Start by identifying the PDF engine

A command that ends in .pdf does not identify the layout system. Pandoc can create PDF through LaTeX, ConTeXt, roff/ms, or an HTML renderer. Margin syntax belongs to the intermediate format and engine, not to the filename.

#	Preview	Product	Price
1		The Flute Book: A Complete Guide for Students and Performers	$9.95	Buy on Amazon

Look for an explicit engine and output format:

pandoc input.html -o output.pdf --pdf-engine=weasyprint
pandoc input.html -o output.pdf --pdf-engine=wkhtmltopdf
pandoc input.html -o output.pdf -t html

Check the installed version as well:

pandoc --version
weasyprint --version
wkhtmltopdf --version

Pandoc’s current manual lists WeasyPrint as the default PDF engine when HTML is the output path, with Prince, wkhtmltopdf, and pagedjs-cli as alternatives. Pandoc 3.4, released 2024-09-09, changed that default to WeasyPrint and deprecated wkhtmltopdf. A project pinned to an older release can therefore behave differently from a new installation.

Fix WeasyPrint margins with @page

WeasyPrint does not provide command-line flags for document margins or page size. Put those values in CSS, either in the HTML or in a stylesheet passed to Pandoc.

#1 Best Overall

The Flute Book: A Complete Guide for Students and Performers

$9.95

Buy on Amazon

/* print.css */
@page {
  size: A4;
  margin: 1.5cm;
}

body {
  margin: 0;
  padding: 0;
}

Then run:

pandoc input.html 
  --to=html 
  --pdf-engine=weasyprint 
  --css=print.css 
  --standalone 
  -o output.pdf

Use the paper size and margin that match your printer or publication specification; 1.5 cm is an example, not a universal recommendation. You can set each side independently:

@page {
  size: Letter portrait;
  margin-top: 12mm;
  margin-right: 15mm;
  margin-bottom: 18mm;
  margin-left: 15mm;
}

If the page boundary is now correct but text is still inset, inspect body and element styles. A rule such as body { padding: 2in; }, a wrapper with large padding, or a fixed-width container can produce the remaining whitespace.

Why Pandoc’s HTML margin variables are misleading

In Pandoc’s HTML variables section, margin-left, margin-right, margin-top, and margin-bottom become CSS padding on the body element. They do not set the paged-media margin box for WeasyPrint. For example:

pandoc input.html -o output.pdf 
  --pdf-engine=weasyprint 
  -V margin-left=2cm -V margin-right=2cm

can leave a large interior border because the values are interpreted as body padding. Replace those variables with an @page rule for the WeasyPrint route, and remove unintended body padding.

Fix wkhtmltopdf margins with page settings

If your command explicitly uses wkhtmltopdf, Pandoc documents the four margin-* variables as page margins. wkhtmltopdf also exposes top, bottom, left, and right margin settings, plus paper size and orientation.

pandoc input.html -o output.pdf 
  --pdf-engine=wkhtmltopdf 
  -V margin-top=10mm 
  -V margin-right=12mm 
  -V margin-bottom=10mm 
  -V margin-left=12mm

Equivalent engine options can be passed when you invoke wkhtmltopdf directly:

wkhtmltopdf 
  --page-size A4 
  --orientation Portrait 
  --margin-top 10mm 
  --margin-right 12mm 
  --margin-bottom 10mm 
  --margin-left 12mm 
  input.html output.pdf

Check header and footer spacing separately. wkhtmltopdf warns that excessive header spacing can place a header outside the page; reducing the header spacing or increasing the top margin can correct that layout. Because wkhtmltopdf is deprecated in Pandoc 3.4, record exact Pandoc and wkhtmltopdf versions before changing a legacy build.

Do not apply LaTeX fixes to an HTML route

LaTeX recipes commonly use geometry settings, but they only affect a LaTeX intermediate document. They will not control CSS page margins in WeasyPrint or wkhtmltopdf. If your command uses --pdf-engine=pdflatex (or another TeX engine), follow the LaTeX-specific variables and packages for that route. If it uses HTML, use CSS and the selected HTML renderer’s options.

Inspect the generated HTML when the blank area remains

Pandoc’s intermediate representation is less expressive than many source and output formats, so it does not promise to preserve every formatting detail, including margin size. Debug the file Pandoc actually renders instead of guessing from the source document.

1. Generate standalone HTML without creating PDF: pandoc input.html --standalone --css=print.css -o debug.html.
2. Open debug.html and inspect linked and embedded stylesheets.
3. Search for @page, body padding or margin, wrapper widths, transforms, and fixed-position headers.
4. Temporarily add an outline to locate the source of the whitespace: * { outline: 1px solid rgba(255,0,0,.15); }.
5. Render again and compare the PDF’s physical page boundary with the text block boundary.

This separates four different causes that look similar in a PDF viewer: page-box margins, body padding, a large paper size, and header or footer layout.

Paper size, orientation, and content can mimic huge margins

• Wrong paper size: A4 content on Letter, or Letter content on A4, can leave uneven edges. Set size in @page or the wkhtmltopdf paper option.
• Orientation mismatch: Landscape content forced onto portrait paper can create broad side gaps or unexpected scaling.
• Fixed-width containers: A wrapper such as width: 900px may be narrower than the printable area. Prefer max-width: 100% for print.
• Browser print CSS: Rules inside @media print can override your normal stylesheet. Place the final @page rule in the stylesheet that is actually loaded.
• Headers and footers: Reserved space can look like a margin even when the page margin is correct.
• Viewer scaling: A PDF viewer’s “fit” or “shrink oversized pages” setting changes the on-screen appearance, not the PDF geometry. Check the document properties or print a test page.

Choosing an engine for a margin-sensitive build

Compare the engine already available in your deployment, the required paper and margin controls, header/footer needs, version maintenance, and compatibility with your CSS. There is no documented universal benchmark that makes one renderer best for every HTML document.

Common failures and targeted fixes

“I set -V margin-left, but WeasyPrint still has a huge border”

Those variables became body padding. Remove them and add @page { margin: ...; }. Then inspect body padding and wrapper styles.

“My CSS is ignored”

Confirm the stylesheet path, use --standalone, and verify the generated HTML contains the stylesheet link or embedded rule. A relative path that works in a browser may fail when the renderer runs from another directory.

“Only the top margin is enormous”

Inspect header and footer spacing, fixed-position elements, and top padding. With wkhtmltopdf, adjust header spacing and margin.top together.

“The result changed after upgrading Pandoc”

Check pandoc --version. Pandoc 3.4 changed the default HTML PDF engine to WeasyPrint and deprecated wkhtmltopdf, so an unpinned command may have switched layout systems.

“The PDF has the right page size but content is clipped”

Reduce body or wrapper padding, remove fixed widths, and check images, tables, and long unbreakable strings. Margin reduction cannot fix content whose own dimensions exceed the page.

Or skip the browser setup

If your goal is to capture a rendered web page rather than build a Pandoc document, ScreenshotNeo provides a one-call screenshot or PDF API. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.

For a PDF or image endpoint, see the ScreenshotNeo documentation. The same request pattern works from the command line:

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

Python:

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}`);

ScreenshotNeo includes 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

Practical checklist

• Record Pandoc and PDF-engine versions.
• Identify whether the route is HTML, LaTeX, or another intermediate format.
• For WeasyPrint, set page size and margins in @page.
• For wkhtmltopdf, set its page-margin options and inspect header spacing.
• Remove unintended body padding and fixed-width wrappers.
• Generate standalone HTML and inspect the CSS Pandoc actually produced.
• Test the physical PDF page size, not only the viewer’s zoom.

Frequently Asked Questions

Does changing PDF viewer zoom fix the margins?

No. Viewer zoom changes the display scale only. Check the PDF’s page geometry and the rendered content box.

Should I always switch from wkhtmltopdf to WeasyPrint?

Not automatically. WeasyPrint is the current default for Pandoc’s HTML route, but an existing wkhtmltopdf build may depend on its behavior. Compare required CSS features and pin versions before migrating.

Can one stylesheet serve both WeasyPrint and wkhtmltopdf?

Often, but their command-line margin controls differ. Keep page geometry in CSS where possible and test each renderer separately, especially headers, footers, and paper sizing.

Quick Recap

Bestseller No. 1

The Flute Book: A Complete Guide for Students and Performers

$9.95

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.