PDF Options

Complete guide to PDF generation options.

PDF Options

All PDF generation endpoints accept an options object to customize the output. This guide covers all available options in detail.

Paper Format

The format option sets the paper size. Default is A4.

Format	Dimensions	Use Case
`A4`	210 × 297 mm	Standard documents (EU)
`Letter`	8.5 × 11 in	Standard documents (US)
`A3`	297 × 420 mm	Posters, large documents
`A5`	148 × 210 mm	Booklets, small documents
`Legal`	8.5 × 14 in	Legal documents (US)
`Tabloid`	11 × 17 in	Newspapers, large spreads

{
  "options": {
    "format": "Letter"
  }
}

Custom Size

For custom paper sizes, use width and height instead of format:

{
  "options": {
    "width": "6in",
    "height": "9in"
  }
}

Orientation

Set landscape: true for landscape orientation:

{
  "options": {
    "format": "A4",
    "landscape": true
  }
}

Orientation	A4 Dimensions	Letter Dimensions
Portrait	210 × 297 mm	8.5 × 11 in
Landscape	297 × 210 mm	11 × 8.5 in

Margins

Set page margins using the margin object. Accepts CSS units: mm, cm, in, px.

{
  "options": {
    "margin": {
      "top": "25mm",
      "bottom": "25mm",
      "left": "20mm",
      "right": "20mm"
    }
  }
}

Common Margin Presets

Preset	Top/Bottom	Left/Right	Total Width
Normal	25mm	20mm	170mm
Narrow	12.7mm	12.7mm	185mm
Wide	25.4mm	50.8mm	108mm
None	0mm	0mm	210mm

Headers and footers require sufficient margins. Recommended minimum: 15mm top/bottom.

Scale

Adjust the rendering scale with scale. Range: 0.1 to 2.0 (default: 1.0).

{
  "options": {
    "scale": 0.8
  }
}

Scale	Effect
`0.5`	50% - Fit more content
`1.0`	100% - Default
`1.5`	150% - Larger text/images
`2.0`	200% - Maximum zoom

Background

Control background rendering with print_background:

{
  "options": {
    "print_background": true
  }
}

Value	Effect
`true`	Include background colors and images (default)
`false`	White background only

Headers and Footers

Add custom headers and footers using HTML:

{
  "options": {
    "header": "<div style='font-size: 10px; text-align: center; width: 100%;'>My Document</div>",
    "footer": "<div style='font-size: 10px; text-align: center; width: 100%;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
    "margin": {
      "top": "40mm",
      "bottom": "30mm"
    }
  }
}

Available Variables

Use these CSS classes in your header/footer HTML:

Class	Value
`pageNumber`	Current page number
`totalPages`	Total page count
`date`	Current date (formatted)
`title`	Document title
`url`	Source URL (URL to PDF only)

Example: Professional Header/Footer

{
  "options": {
    "header": "<div style='width: 100%; padding: 0 20mm; font-size: 9px; color: #666; display: flex; justify-content: space-between;'><span>Company Name</span><span>Confidential</span></div>",
    "footer": "<div style='width: 100%; padding: 0 20mm; font-size: 9px; color: #666; display: flex; justify-content: space-between;'><span>Generated: <span class='date'></span></span><span>Page <span class='pageNumber'></span> of <span class='totalPages'></span></span></div>",
    "margin": {
      "top": "35mm",
      "bottom": "25mm"
    }
  }
}

Wait Time (URL to PDF)

For pages with dynamic content, use wait_for to wait before capturing:

{
  "url": "https://example.com/dashboard",
  "options": {
    "wait_for": 3000
  }
}

Value	Description
`0`	No wait (default)
`1000`	1 second
`5000`	5 seconds
`30000`	30 seconds (maximum)

Viewport (URL to PDF)

Set the browser viewport size for rendering:

{
  "options": {
    "viewport": {
      "width": 1920,
      "height": 1080
    }
  }
}

Recommended Viewports

Device	Width	Height
Desktop HD	1920	1080
Desktop	1440	900
Laptop	1366	768
Tablet	1024	768
Mobile	390	844

Full Page (URL to PDF)

Capture the entire scrollable page:

{
  "options": {
    "full_page": true
  }
}

This may result in multi-page PDFs for long pages.

Complete Example

{
  "markdown": "# Report\n\nContent here...",
  "theme": "corporate",
  "options": {
    "format": "A4",
    "landscape": false,
    "margin": {
      "top": "35mm",
      "bottom": "25mm",
      "left": "20mm",
      "right": "20mm"
    },
    "scale": 1.0,
    "print_background": true,
    "header": "<div style='font-size: 9px; text-align: center; width: 100%;'>Monthly Report - January 2025</div>",
    "footer": "<div style='font-size: 9px; text-align: center; width: 100%;'>Page <span class='pageNumber'></span></div>"
  }
}