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
| Option | Type | Default | Description |
|---|---|---|---|
fileName | string | "document" | Output filename (without extension) |
format | string | "A4" | Paper format (A4, Letter, etc.) |
orientation | string | "portrait" | Page orientation |
width | string | - | Custom page width (overrides format) |
height | string | - | Custom page height (overrides format) |
margin | object | 1cm all sides | Page margins |
preferCSSPageSize | boolean | false | Use CSS @page size rules |
autoPageBreaks | boolean | true | Enable automatic page break optimization |
watermark | object | - | Text watermark configuration |
host | boolean | false | Store 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
| Format | Dimensions |
|---|---|
A4 | 210mm × 297mm (default) |
Letter | 8.5in × 11in |
Legal | 8.5in × 14in |
Tabloid | 11in × 17in |
A3 | 297mm × 420mm |
A5 | 148mm × 210mm |
A0 - A6 | Standard 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"
}| Value | Description |
|---|---|
portrait | Standard vertical orientation (default) |
landscape | Horizontal 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
| Plan | Hosted PDFs | Retention |
|---|---|---|
| Hobby | 10 | 1 day |
| Pro | 500 | 7 days |
| Enterprise | 10,000 | 30 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
| Option | Type | Default | Description |
|---|---|---|---|
text | string | "WATERMARK" | Text to display |
fontSize | number | 48 | Font size in points |
opacity | number | 0.3 | Transparency (0.0 = invisible, 1.0 = solid) |
rotation | number | -45 | Rotation angle in degrees |
color | object | {r:0.5,g:0.5,b:0.5} | RGB color values (0.0 to 1.0) |
position | string | "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"
}
}{
"watermark": {
"text": "© 2024 Your Company",
"fontSize": 12,
"opacity": 0.5,
"rotation": 0,
"color": { "r": 0, "g": 0, "b": 0 },
"position": "bottom-right"
}
}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
| Attribute | Default | Description |
|---|---|---|
data-qr | Required | URL or text to encode |
data-qr-size | 200 | Size in pixels |
data-qr-margin | 1 | White 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 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.jsonconst 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"
}| Option | Type | Default | Description |
|---|---|---|---|
outputType | string | "zip" | Output format: "zip" or "merged" |
fileName | string | "batch" | Base filename for output |
Output Types
zip: Each HTML file becomes a separate PDF, all bundled in a ZIP filemerged: 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"
}
}