How to Set PDF Page Size and Margins in DocRaptor

Set a PDF’s page size, orientation, and margins in a CSS @page rule included with the HTML you send to DocRaptor. For example, this selects landscape A4 with a uniform 10 mm margin:

@page {
  size: A4 landscape;
  margin: 10mm;
}

DocRaptor’s documented default is US Letter portrait with a 0.75-inch margin. Explicitly set the page format and margins when the output must match a print specification or a particular document layout. DocRaptor’s size and orientation guide and page styling guide describe these CSS controls.

1. Add the page rule to your document

Put the CSS in a <style> element in the HTML sent to DocRaptor, or in a stylesheet included with that HTML. Keep page setup in @page; ordinary element styling such as fonts and colors can remain in your normal CSS.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    @page {
      size: A4 portrait;
      margin: 15mm 18mm;
    }
    body { font-family: sans-serif; }
  </style>
</head>
<body>
  <h1>Quarterly report</h1>
  <p>The page format and printable content area are controlled separately.</p>
</body>
</html>

Choose a named paper size when one matches the delivery requirement. Use explicit width and height for a custom format. Size and margin are independent: changing the page size does not choose the margins for you.

2. Choose a page size and orientation

A named size without an orientation is portrait. Add landscape after the size to switch orientation:

@page { size: A4; }             /* A4 portrait */
@page { size: A4 landscape; }   /* A4 landscape */

DocRaptor documents US Letter as 8.5 × 11 inches and A4 as 210 × 297 mm. Its page size keyword reference includes other ISO, US, ANSI, architectural, and book formats. Check the required paper standard before choosing a keyword; do not assume that “Letter” and A4 are interchangeable.

Custom page dimensions

If no named format fits, provide width and height with CSS units:

@page { size: 22cm 24cm; }
@page { size: 4in 8in; }

For custom dimensions, provide width first and height second. Use a consistent unit such as millimeters, centimeters, inches, or points and verify that the resulting page is the expected orientation. The DocRaptor custom page size tutorial shows custom-size CSS in an HTML document submitted through its API.

3. Set uniform or per-side margins

The margin shorthand sets all four sides at once. You can also declare each side separately when the layout needs more room at the top, bottom, or binding edge:

@page {
  size: A4;
  margin: 10mm;
}

@page {
  size: A4;
  margin-top: 20mm;
  margin-right: 15mm;
  margin-bottom: 20mm;
  margin-left: 15mm;
}

CSS shorthand can also express different vertical and horizontal margins, as in margin: 15mm 20mm. After changing margins, inspect the page breaks: larger margins reduce the area available to the main content and can move text or tables onto additional pages. DocRaptor’s margins and bleed guide covers margin behavior and examples.

First-page and binding layouts

For a cover or title page with different spacing, use a first-page selector:

@page:first { margin: 0; }

For a binding layout, DocRaptor documents margin-inside and margin-outside so the binding edge can have different space from the outer edge. Confirm the resulting layout for both odd and even pages when the document will be printed as a bound set. A zero margin is appropriate for an intended full-bleed page; otherwise it can place content at the physical edge and outside a printer’s printable area.

4. Reserve space for headers and footers

Headers and footers use page margin areas. Set enough top or bottom margin to accommodate them; DocRaptor notes that these areas do not automatically grow to fit their contents. A margin that is too small can crop or hide a header or footer. Increasing the margin reserves more space but also reduces the main content area, so recheck pagination after each change. See DocRaptor’s page regions guide and headers and footers guide.

5. Submit a complete HTML document to DocRaptor

The page rule must be part of the document or stylesheet DocRaptor receives. This minimal Python example uses the documented HTML-in-API approach; supply your own account credentials and follow the current DocRaptor API reference for authentication and response handling:

import requests

html = """<!doctype html>
<html><head><style>
@page { size: A4 landscape; margin: 10mm; }
</style></head><body>
<h1>Landscape report</h1>
<p>This HTML includes its PDF page setup.</p>
</body></html>"""

response = requests.post(
    "https://docraptor.com/docs",
    auth=("YOUR_API_KEY", ""),
    data={
        "doc[document_type]": "pdf",
        "doc[document_content]": html,
        "doc[name]": "landscape-report.pdf",
        "doc[test]": "true",
    },
    timeout=90,
)
response.raise_for_status()
with open("landscape-report.pdf", "wb") as pdf:
    pdf.write(response.content)

Use DocRaptor’s current API documentation to confirm the endpoint, authentication format, and request fields for your account and integration. The CSS rule itself belongs in the submitted HTML or its included stylesheet.

Common problems and fixes

Symptom	Likely cause	What to check
PDF remains Letter portrait	The `@page` rule is missing from the submitted document or stylesheet, or another applicable rule overrides it.	Inspect the exact HTML and stylesheets sent to DocRaptor; confirm the rule is present and applies to the generated pages.
Landscape pages appear portrait	The orientation was omitted or the size declaration is malformed.	Use a declaration such as `size: A4 landscape`.
Header or footer is cut off	The top or bottom page margin is too small for the page-region content.	Increase the relevant margin and regenerate; the region does not automatically enlarge the margin.
Text moves to extra pages	Margins were increased, shrinking the content area.	Review page breaks and adjust the layout or margins while keeping the required print dimensions.
Custom page is wrong size	Width and height, units, or order do not match the intended dimensions.	Specify width followed by height with explicit units, then inspect the generated PDF’s page dimensions.
Content is clipped at page edges	Margins are zero or too small for the content or the physical printer.	Use suitable margins unless full bleed is intended, and account for printer limits for physical output.

Performance, reliability, and cost considerations

Page size and margins are document layout settings; choose them for the destination before tuning content flow. For reliable output, keep the page rule with the submitted HTML or a stylesheet whose availability is controlled, and review representative PDFs after changing dimensions, margins, headers, or footers. This avoids relying on an undocumented assumption about defaults or pagination. DocRaptor’s documentation identifies its default format and margin, but the cited guidance does not provide a performance benchmark or per-document cost estimate; consult its current service and pricing details for those specifics.

Or skip the browser setup

If your goal is to capture a web page as an image or PDF rather than render your own HTML through DocRaptor, ScreenshotNeo is a website screenshot API and MCP server. A single request can return a screenshot or PDF; see the ScreenshotNeo API documentation for options.

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

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)

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(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes cookie banners, popups, and chat widgets before capture. 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 1,000 free screenshots a month, with no card required.

FAQ

What is DocRaptor’s default PDF page setup?

The documented default is US Letter in portrait with a 0.75-inch margin. Set an explicit @page rule when your output needs a different format.

Can page size and margins be set in separate rules?

They can be declared separately, but placing both in the applicable @page rule makes the intended page setup easy to inspect.

When should I use a zero margin?

Use it for a layout designed for full bleed. For ordinary documents or physical printing, leave suitable space around the content.

Why did changing margins alter page count?

Margins reduce or expand the area available to the main content. A smaller content area can cause text and other elements to flow onto more pages.