Skip to content

Commit e1b08c1

Browse files
carbogninalbertocarbogninalberto
committed
docs: expand README with detailed device, render, PDF, image, and video options for enhanced configuration
1 parent c1dd760 commit e1b08c1

1 file changed

Lines changed: 242 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 242 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,12 +86,109 @@ docker run --platform linux/amd64 -p 3000:3000 render
8686
| `url` | string | One of `url` or `html` | URL to render |
8787
| `html` | string | One of `url` or `html` | Raw HTML content to render |
8888
| `type` | string | Yes | `image`, `pdf`, `video`, or `html` |
89-
| `device` | object | No | Viewport settings (width, height, userAgent) |
90-
| `render` | object | No | Render options (waitTime, fullPage, scroll) |
89+
| `headers` | object | No | Custom HTTP headers to send with the request |
90+
| `device` | object | No | Viewport settings (width, height, scale, userAgent, locale, timezone) |
91+
| `render` | object | No | Render options (waitTime, fullPage, scroll, block) |
9192
| `image` | object | No | Image settings (type, quality, compression, crop, resize, rotation) |
92-
| `pdf` | object | No | PDF settings (format, margins, orientation, header/footer) |
93+
| `pdf` | object | No | PDF settings (format, width, height, margins, orientation, header/footer) |
9394
| `video` | object | No | Video settings (fps, duration, codec, bitrate, crf, preset) |
9495

96+
### Device Options
97+
98+
Configure the browser viewport and device emulation.
99+
100+
| Parameter | Type | Default | Description |
101+
|-----------|------|---------|-------------|
102+
| `width` | number | `1920` | Viewport width in pixels |
103+
| `height` | number | `1080` | Viewport height in pixels |
104+
| `scale` | number | `1` | Device scale factor (DPR) |
105+
| `userAgent` | string | Chrome default | Custom user agent string |
106+
| `locale` | string | `en-US` | Browser locale (e.g., `fr-FR`, `de-DE`) |
107+
| `timezone` | string | `UTC` | Timezone (e.g., `Europe/London`, `America/New_York`) |
108+
| `javascriptEnabled` | boolean | `true` | Enable/disable JavaScript execution |
109+
110+
### Render Options
111+
112+
Control page loading and rendering behavior.
113+
114+
| Parameter | Type | Default | Description |
115+
|-----------|------|---------|-------------|
116+
| `waitTime` | number | `0` | Additional wait time after page load (ms) |
117+
| `timeout` | number | `30000` | Page load timeout (ms) |
118+
| `fullPage` | boolean | `false` | Capture full scrollable page (images only) |
119+
| `triggerLazyAnimations` | boolean | `false` | Scroll page to trigger lazy-loaded content |
120+
| `waitUntil` | string | `networkidle0` | Wait condition: `load`, `domcontentloaded`, `networkidle0`, `networkidle2` |
121+
| `scroll.position` | number | `0` | Scroll to position before capture (px) |
122+
| `scroll.animate` | boolean | `false` | Enable scroll animation (video) |
123+
| `scroll.duration` | number | `5000` | Scroll animation duration (ms) |
124+
| `scroll.animation` | string | `smooth` | Scroll animation style |
125+
| `block.cookies` | boolean | `false` | Block cookie consent banners |
126+
| `block.ads` | boolean | `false` | Block advertisements |
127+
| `block.trackers` | boolean | `false` | Block tracking scripts |
128+
| `block.banners` | boolean | `false` | Block promotional banners |
129+
130+
### PDF Options
131+
132+
Full control over PDF generation. Supports custom page dimensions with units.
133+
134+
| Parameter | Type | Default | Description |
135+
|-----------|------|---------|-------------|
136+
| `format` | string | `A4` | Paper format: `A0`-`A6`, `Letter`, `Legal`, `Tabloid`, `Ledger` |
137+
| `width` | string | - | Custom width with units (e.g., `210mm`, `8.5in`, `600px`) |
138+
| `height` | string | - | Custom height with units (e.g., `297mm`, `11in`, `800px`) |
139+
| `landscape` | boolean | `false` | Landscape orientation |
140+
| `scale` | number | `1` | Scale of the webpage rendering (0.1 to 2) |
141+
| `printBackground` | boolean | `true` | Print background graphics |
142+
| `displayHeaderFooter` | boolean | `false` | Display header and footer |
143+
| `headerTemplate` | string | `""` | HTML template for header |
144+
| `footerTemplate` | string | `""` | HTML template for footer |
145+
| `pageRanges` | string | `""` | Page ranges to print (e.g., `1-5`, `1,3,5`) |
146+
| `preferCSSPageSize` | boolean | `false` | Use CSS-defined page size |
147+
| `omitBackground` | boolean | `false` | Hide default white background |
148+
| `margin.top` | string | `0px` | Top margin with units |
149+
| `margin.right` | string | `0px` | Right margin with units |
150+
| `margin.bottom` | string | `0px` | Bottom margin with units |
151+
| `margin.left` | string | `0px` | Left margin with units |
152+
153+
**Supported units:** `px`, `in`, `cm`, `mm`
154+
155+
> **Note:** When using custom `width` or `height`, the `format` option is automatically ignored.
156+
157+
### Image Options
158+
159+
Configure screenshot output format and post-processing.
160+
161+
| Parameter | Type | Default | Description |
162+
|-----------|------|---------|-------------|
163+
| `type` | string | `png` | Output format: `png`, `jpeg`, `webp`, `gif`, `avif` |
164+
| `quality` | number | `100` | Image quality (0-100, for jpeg/webp) |
165+
| `compression` | number | `0` | PNG compression level (0-9, 0=fastest) |
166+
| `smooth` | boolean | `true` | Enable adaptive filtering for PNG |
167+
| `resize` | number | `1` | Resize factor (0.1 to 3) |
168+
| `rotate` | number | `0` | Rotation angle (0-360 degrees) |
169+
| `roundedBorders` | number/boolean | `false` | Border radius in pixels |
170+
| `padding` | number | `0` | Padding in pixels |
171+
| `crop.left` | number | - | Crop area left offset |
172+
| `crop.top` | number | - | Crop area top offset |
173+
| `crop.width` | number | - | Crop area width |
174+
| `crop.height` | number | - | Crop area height |
175+
176+
### Video Options
177+
178+
Configure MP4 video recording with scroll animation.
179+
180+
| Parameter | Type | Default | Description |
181+
|-----------|------|---------|-------------|
182+
| `fps` | number | `60` | Frames per second |
183+
| `followNewTab` | boolean | `true` | Follow navigation to new tabs |
184+
| `videoCrf` | number | `23` | Constant Rate Factor (0-51, lower=better quality) |
185+
| `videoCodec` | string | `libx264` | Video codec |
186+
| `videoPreset` | string | `ultrafast` | Encoding preset: `ultrafast`, `superfast`, `veryfast`, `faster`, `fast`, `medium`, `slow`, `slower`, `veryslow` |
187+
| `videoBitrate` | number | `3000` | Bitrate in kbps (500-10000) |
188+
| `recordDurationLimit` | number | `30` | Maximum recording duration in seconds |
189+
| `videoFrame.width` | number | `1920` | Video frame width |
190+
| `videoFrame.height` | number | `1080` | Video frame height |
191+
95192
### Examples
96193

97194
**Screenshot from URL:**
@@ -116,6 +213,72 @@ curl -X POST http://localhost:3000/render \
116213
--output output.pdf
117214
```
118215

216+
**PDF with custom dimensions (mm):**
217+
218+
```bash
219+
curl -X POST http://localhost:3000/render \
220+
-H "Content-Type: application/json" \
221+
-d '{
222+
"url": "https://example.com",
223+
"type": "pdf",
224+
"pdf": {
225+
"width": "210mm",
226+
"height": "400mm",
227+
"margin": {"top": "10mm", "bottom": "10mm", "left": "10mm", "right": "10mm"}
228+
}
229+
}' \
230+
--output custom-size.pdf
231+
```
232+
233+
**PDF with custom dimensions (inches - US Letter):**
234+
235+
```bash
236+
curl -X POST http://localhost:3000/render \
237+
-H "Content-Type: application/json" \
238+
-d '{
239+
"url": "https://example.com",
240+
"type": "pdf",
241+
"pdf": {
242+
"width": "8.5in",
243+
"height": "11in",
244+
"margin": {"top": "0.5in", "bottom": "0.5in", "left": "0.5in", "right": "0.5in"}
245+
}
246+
}' \
247+
--output letter.pdf
248+
```
249+
250+
**Receipt/ticket PDF (narrow format):**
251+
252+
```bash
253+
curl -X POST http://localhost:3000/render \
254+
-H "Content-Type: application/json" \
255+
-d '{
256+
"html": "<html><body style=\"font-family:monospace\"><h2>RECEIPT</h2><hr><p>Item 1...$10.00</p><p>Total: $10.00</p></body></html>",
257+
"type": "pdf",
258+
"pdf": {"width": "80mm", "height": "200mm", "margin": {"top": "5mm", "bottom": "5mm", "left": "5mm", "right": "5mm"}}
259+
}' \
260+
--output receipt.pdf
261+
```
262+
263+
**PDF with header and footer:**
264+
265+
```bash
266+
curl -X POST http://localhost:3000/render \
267+
-H "Content-Type: application/json" \
268+
-d '{
269+
"url": "https://example.com",
270+
"type": "pdf",
271+
"pdf": {
272+
"format": "A4",
273+
"displayHeaderFooter": true,
274+
"headerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%\">Company Name</div>",
275+
"footerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
276+
"margin": {"top": "20mm", "bottom": "20mm", "left": "10mm", "right": "10mm"}
277+
}
278+
}' \
279+
--output with-header-footer.pdf
280+
```
281+
119282
**WebP image with custom quality:**
120283

121284
```bash
@@ -148,13 +311,89 @@ curl -X POST http://localhost:3000/render \
148311
--output page.html
149312
```
150313

314+
**Mobile viewport screenshot:**
315+
316+
```bash
317+
curl -X POST http://localhost:3000/render \
318+
-H "Content-Type: application/json" \
319+
-d '{
320+
"url": "https://example.com",
321+
"type": "image",
322+
"device": {
323+
"width": 375,
324+
"height": 812,
325+
"scale": 2,
326+
"userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15"
327+
}
328+
}' \
329+
--output mobile.png
330+
```
331+
332+
**Full page screenshot with lazy loading:**
333+
334+
```bash
335+
curl -X POST http://localhost:3000/render \
336+
-H "Content-Type: application/json" \
337+
-d '{
338+
"url": "https://example.com",
339+
"type": "image",
340+
"render": {
341+
"fullPage": true,
342+
"triggerLazyAnimations": true,
343+
"waitTime": 1000
344+
}
345+
}' \
346+
--output fullpage.png
347+
```
348+
349+
**Cropped and resized screenshot:**
350+
351+
```bash
352+
curl -X POST http://localhost:3000/render \
353+
-H "Content-Type: application/json" \
354+
-d '{
355+
"url": "https://example.com",
356+
"type": "image",
357+
"image": {
358+
"type": "png",
359+
"crop": {"left": 0, "top": 0, "width": 800, "height": 600},
360+
"resize": 0.5
361+
}
362+
}' \
363+
--output cropped.png
364+
```
365+
366+
**Screenshot with custom headers and locale:**
367+
368+
```bash
369+
curl -X POST http://localhost:3000/render \
370+
-H "Content-Type: application/json" \
371+
-d '{
372+
"url": "https://example.com",
373+
"type": "image",
374+
"headers": {"Authorization": "Bearer token123"},
375+
"device": {"locale": "fr-FR", "timezone": "Europe/Paris"}
376+
}' \
377+
--output french.png
378+
```
379+
151380
**GET request with config parameter:**
152381

153382
```bash
154383
curl "http://localhost:3000/render?config=%7B%22url%22%3A%22https%3A%2F%2Fexample.com%22%2C%22type%22%3A%22image%22%7D" \
155384
--output screenshot.png
156385
```
157386

387+
### Demo Script
388+
389+
A comprehensive test script is included to demonstrate PDF custom dimensions:
390+
391+
```bash
392+
./pdf.demo.examples.sh
393+
```
394+
395+
This generates 26 PDFs with various sizes (A3, A5, Letter, Legal, custom dimensions in mm/in/cm/px, receipts, posters, etc.) in the `pdf-demo-examples/` directory.
396+
158397
## Configuration
159398

160399
All settings are driven by environment variables with sensible defaults.

0 commit comments

Comments
 (0)