SyntaxdocSyntaxdoc

Options

Customize your PDF output with all available configuration options

Customize your PDF output with these configuration options. All options are passed in the options field when uploading files via form-data.

Options Reference

OptionTypeDefaultDescription
fileNamestring"document"Output filename (without extension)
formatstring"A4"Paper format (A4, Letter, etc.)
orientationstring"portrait"Page orientation
widthstring-Custom page width (overrides format)
heightstring-Custom page height (overrides format)
marginobject1cm all sidesPage margins
preferCSSPageSizebooleanfalseUse CSS @page size rules
autoPageBreaksbooleantrueEnable automatic page break optimization
watermarkobject-Text watermark configuration
hostbooleanfalseStore PDF on server with shareable URL

File Name

Set the output filename for your PDF.

{
  "fileName": "invoice-2024-001"
}

The .pdf extension is automatically added. When downloading, the file will be named invoice-2024-001.pdf.


Paper Format

Control the page size of your PDF.

{
  "format": "A4"
}

Available Formats

FormatDimensions
A4210mm × 297mm (default)
Letter8.5in × 11in
Legal8.5in × 14in
Tabloid11in × 17in
A3297mm × 420mm
A5148mm × 210mm
A0 - A6Standard A-series sizes

Custom Dimensions

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

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

When width and height are specified, the format option is ignored. Supported units: px, in, cm, mm.


Orientation

Set landscape orientation for wide content like tables or charts.

{
  "orientation": "landscape"
}
ValueDescription
portraitStandard vertical orientation (default)
landscapeHorizontal orientation for wide content

Orientation only applies when using format. Custom width and height dimensions are used as-is regardless of orientation.


Margins

Set page margins using CSS units (px, in, cm, mm).

{
  "margin": {
    "top": "1in",
    "right": "0.75in",
    "bottom": "1in",
    "left": "0.75in"
  }
}

Default Margins

When margins are not specified, the default is 1cm on all sides:

{
  "margin": {
    "top": "1cm",
    "right": "1cm",
    "bottom": "1cm",
    "left": "1cm"
  }
}

Individual Margin Override

You can specify individual margins - unspecified sides use the default:

{
  "margin": {
    "top": "2cm",
    "bottom": "2cm"
  }
}

CSS Page Size

Use the page size defined in CSS @page rules instead of the format option.

{
  "preferCSSPageSize": true
}

Your HTML can then define the page size:

<style>
  @page {
    size: 6in 9in;
    margin: 1in;
  }
</style>

This is useful for documents that need precise control over page layout, such as books, business cards, or custom-sized certificates.


Host Option (PDF Hosting)

Store the generated PDF on the server and receive a shareable URL instead of the binary PDF.

{
  "host": true,
  "fileName": "my-report"
}

Response with Hosting

When host: true, the response includes:

{
  "url": "https://api.syntaxdoc.com/pdf/hosted/abc123.pdf",
  "pdfId": "abc123",
  "expiresAt": "2024-01-15T00:00:00.000Z"
}

Hosting Limits by Plan

PlanHosted PDFsRetention
Hobby101 day
Pro5007 days
Enterprise10,00030 days

If you've reached your hosting limit, you'll receive a 429 error with code HOSTED_PDF_LIMIT_REACHED. Delete existing hosted PDFs or upgrade your plan.


Page Breaks

Control how content flows across pages with automatic optimization (enabled by default).

{
  "autoPageBreaks": true  // Default: true
}

Automatic Features

When autoPageBreaks is enabled (default), SyntaxDoc automatically:

  • ✅ Splits large tables (20+ rows) across pages
  • ✅ Repeats table headers on each page
  • ✅ Prevents headings from being orphaned at page bottom
  • ✅ Groups table rows intelligently for better breaks
  • ✅ Prevents widows and orphans in paragraphs

Manual Control in HTML

Use CSS classes or data attributes in your HTML:

<!-- Force page break before element -->
<div class="page-break-before">
  <h1>New Chapter</h1>
</div>

<!-- Keep content together -->
<div class="keep-together">
  <h2>Important Section</h2>
  <p>Content that stays together...</p>
</div>

<!-- Using data attributes -->
<section data-page-break="before">
  <h1>Chapter 2</h1>
</section>

<div data-keep-together>
  <h3>Table</h3>
  <table>...</table>
</div>

Full page break documentation →


Watermark

Add text watermarks to every page of your PDF for branding, security, or document status.

{
  "watermark": {
    "text": "CONFIDENTIAL",
    "fontSize": 60,
    "opacity": 0.2,
    "rotation": -45,
    "color": { "r": 1, "g": 0, "b": 0 },
    "position": "diagonal"
  }
}

Watermark Options

OptionTypeDefaultDescription
textstring"WATERMARK"Text to display
fontSizenumber48Font size in points
opacitynumber0.3Transparency (0.0 = invisible, 1.0 = solid)
rotationnumber-45Rotation angle in degrees
colorobject{r:0.5,g:0.5,b:0.5}RGB color values (0.0 to 1.0)
positionstring"diagonal"Position: diagonal, center, top-left, top-right, bottom-left, bottom-right

Common Watermark Styles

{
  "watermark": {
    "text": "CONFIDENTIAL",
    "fontSize": 60,
    "opacity": 0.2,
    "rotation": -45,
    "color": { "r": 1, "g": 0, "b": 0 }
  }
}
{
  "watermark": {
    "text": "DRAFT",
    "fontSize": 72,
    "opacity": 0.15,
    "rotation": -45,
    "color": { "r": 0.5, "g": 0.5, "b": 0.5 }
  }
}
{
  "watermark": {
    "text": "SAMPLE",
    "fontSize": 80,
    "opacity": 0.1,
    "rotation": 0,
    "color": { "r": 0, "g": 0, "b": 0 },
    "position": "center"
  }
}

Full watermark documentation →


QR Codes (Inline)

Generate QR codes automatically by adding data-qr attributes to your HTML - no configuration needed in options!

<!-- In your HTML file -->
<img data-qr="https://yourapp.com/verify/cert-12345" 
     data-qr-size="200" 
     data-qr-error-correction="H"
     alt="Verification QR Code" />

The QR code is automatically generated and embedded during PDF creation.

QR Code Attributes

AttributeDefaultDescription
data-qrRequiredURL or text to encode
data-qr-size200Size in pixels
data-qr-margin1White margin (0-10 modules)
data-qr-error-correction"M"Error correction: L, M, Q, H
data-qr-dark-color"#000000"Dark modules color
data-qr-light-color"#ffffff"Light modules color

Full QR code documentation →


Full Example

# Create options as JSON string
curl -X POST https://api.syntaxdoc.com/pdf/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@index.html" \
  -F "files=@styles.css" \
  -F 'options={"fileName":"report","format":"Letter","orientation":"landscape","margin":{"top":"1in","bottom":"1in"},"host":true}' \
  -o response.json
const formData = new FormData();

// Add HTML file
formData.append('files', htmlFile);

// Add options
formData.append('options', JSON.stringify({
  fileName: 'quarterly-report',
  format: 'Letter',
  orientation: 'landscape',
  margin: {
    top: '1in',
    right: '0.75in',
    bottom: '1in',
    left: '0.75in'
  },
  host: true
}));

const response = await fetch('https://api.syntaxdoc.com/pdf/generate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
  },
  body: formData
});

if (response.headers.get('content-type')?.includes('application/json')) {
  // Hosted PDF - returns URL
  const data = await response.json();
  console.log('PDF URL:', data.url);
  console.log('Expires:', data.expiresAt);
} else {
  // Direct PDF binary
  const pdfBlob = await response.blob();
  // Save or display the PDF
}
import requests
import json

url = 'https://api.syntaxdoc.com/pdf/generate'
headers = {'X-API-Key': 'YOUR_API_KEY'}

# Prepare files
files = [
    ('files', ('index.html', open('index.html', 'rb'), 'text/html')),
    ('files', ('styles.css', open('styles.css', 'rb'), 'text/css')),
]

# Prepare options
options = {
    'fileName': 'quarterly-report',
    'format': 'Letter',
    'orientation': 'landscape',
    'margin': {
        'top': '1in',
        'right': '0.75in',
        'bottom': '1in',
        'left': '0.75in'
    },
    'host': True
}

data = {'options': json.dumps(options)}

response = requests.post(url, headers=headers, files=files, data=data)

if response.headers.get('content-type', '').startswith('application/json'):
    # Hosted PDF
    result = response.json()
    print(f"PDF URL: {result['url']}")
    print(f"Expires: {result['expiresAt']}")
else:
    # Direct PDF binary
    with open('report.pdf', 'wb') as f:
        f.write(response.content)

Merge Options

When using the /pdf/merge endpoint, these options are available:

{
  "fileName": "combined-documents",
  "host": true
}

Paper format and margin options don't apply to merge operations since you're combining existing PDFs.


Batch Options

When using the /pdf/generate-batch endpoint for multiple HTML files:

{
  "outputType": "zip",
  "fileName": "batch-results"
}
OptionTypeDefaultDescription
outputTypestring"zip"Output format: "zip" or "merged"
fileNamestring"batch"Base filename for output

Output Types

  • zip: Each HTML file becomes a separate PDF, all bundled in a ZIP file
  • merged: All HTML files are converted and merged into a single PDF

Common Use Cases

Invoice / Receipt

{
  "fileName": "invoice-2024-001",
  "format": "A4",
  "margin": {
    "top": "0.5in",
    "right": "0.5in", 
    "bottom": "0.5in",
    "left": "0.5in"
  }
}

Certificate / Diploma

{
  "fileName": "certificate-john-doe",
  "format": "Letter",
  "orientation": "landscape",
  "host": true
}

Book / eBook

{
  "width": "6in",
  "height": "9in",
  "margin": {
    "top": "0.75in",
    "right": "0.5in",
    "bottom": "0.75in",
    "left": "0.75in"
  }
}

Wide Report / Spreadsheet

{
  "format": "Tabloid",
  "orientation": "landscape",
  "margin": {
    "top": "0.25in",
    "right": "0.25in",
    "bottom": "0.25in",
    "left": "0.25in"
  }
}

Business Card

{
  "width": "3.5in",
  "height": "2in",
  "margin": {
    "top": "0",
    "right": "0",
    "bottom": "0",
    "left": "0"
  }
}

On this page