n8n-nodes-gotenberg-pdf

This is an n8n community node for Gotenberg, a containerized API for seamless PDF conversion.

Package Name: n8n-nodes-gotenberg-pdf

Features

URL to PDF: Convert any web page to PDF using Chromium
HTML to PDF: Convert HTML content directly to PDF with image support
Merge PDFs: Combine multiple PDF files into a single document (alphanumerically sorted)
Split PDFs: Split PDF files by page intervals or specific page ranges
Standardized Paper Sizes: A4, Letter, Legal, A3, A5, Tabloid + Custom sizes
Advanced Options: Margins, scaling, page ranges, accessibility features, PDF/A conversion
Clean UI: Essential options visible, advanced features organized in collections
Binary Output: PDF/ZIP files are returned as binary data for further processing
Error Handling: Comprehensive error handling with optional continue-on-fail
Tool Support: Can be used as an AI agent tool

Installation

To install this community node, follow these steps:

Install n8n (if not already installed):
```
npm install n8n -g
```
Install this community node:
```
npm install n8n-nodes-gotenberg-pdf
```
Start n8n:
```
n8n start
```

Prerequisites

You need a running Gotenberg instance. You can start one using Docker:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Or with custom configuration:

docker run --rm -p 3000:3000 --name gotenberg gotenberg/gotenberg:8

Configuration

Credentials

Before using the Gotenberg node, you need to configure the credentials:

Go to Credentials in your n8n instance
Create new credentials of type Gotenberg API
Configure:
- Base URL: The URL of your Gotenberg instance (e.g., http://localhost:3000 or http://gotenberg:3000)
- API Key: Optional, if your Gotenberg instance requires authentication

Note: If you're using a custom Gotenberg setup, make sure to use the correct URL path. For example, if your instance is at http://gotenberg:3000/forms/chromium/convert/url, set the Base URL to http://gotenberg:3000.

Node Configuration

The Gotenberg node supports the following operations:

URL to PDF

Convert any web page to PDF format.

Required Parameters:

URL: The web page URL to convert

HTML to PDF

Convert HTML content directly to PDF format.

Required Parameters:

HTML Content: The HTML content to convert (with built-in editor)

Additional Files (Optional):

Images: Upload image files that can be referenced in your HTML using <img src="filename.png" />

Merge PDFs

Combine multiple PDF files into a single document. Files are merged alphanumerically.

Required Parameters:

PDF Files: The binary field name containing the PDF files to merge (default: "data")

Split PDF

Split a PDF file into multiple files by intervals or specific page ranges.

Required Parameters:

PDF File: The binary field name containing the PDF file to split (default: "data")
Split Mode: Choose between "intervals" or "pages"
Split Span:
- For intervals: Number of pages per split (e.g., "2" for every 2 pages)
- For pages: Page ranges (e.g., "1-3,5-7,10")

Optional Parameters:

Unify Split Pages: (Pages mode only) Whether to put extracted pages into a single file or separate files

Common Configuration

Paper Size Options:

Standard Sizes: A4 (default), Letter, Legal, A3, A5, Tabloid
Custom Size: Define custom width and height with units (in, mm, cm, pt, px, pc)
Landscape: Enable landscape orientation

Advanced Options:

Margins: Custom margins with unit support
Print Background: Include background graphics
Scale: Webpage rendering scale (0.1 to 2.0)
Single Page: Print entire content on one page
Page Ranges: Specify which pages to print (e.g., "1-5, 8, 11-13")
CSS Page Size: Prefer CSS-defined page size
Tagged PDF: Generate accessible/tagged PDF
Omit Background: Enable transparency by hiding default white background
Wait Delay: Time to wait before conversion (URL operation only)

Usage Examples

Basic URL to PDF Conversion

Add the Gotenberg node to your workflow
Select "URL to PDF" operation
Enter the URL: https://example.com
Choose paper size (default: A4)
Execute the node

HTML to PDF Conversion

Add the Gotenberg node to your workflow
Select "HTML to PDF" operation
Enter or paste your HTML content in the editor
Choose paper size and orientation
Execute the node

Note: The HTML to PDF feature currently supports inline HTML content. For full functionality with external assets (images, stylesheets, fonts), you may need to embed them as base64 or use absolute URLs. Future versions will support multi-file HTML uploads.

Advanced Configuration

For more control over the PDF output:

Select your preferred paper size or choose "Custom Size"
Enable landscape mode if needed
Expand "Advanced Options" for:
- Custom margins with units (e.g., "1in", "25.4mm")
- Print background graphics
- Scale adjustment
- Page range selection
- Accessibility features

The output will contain:

JSON data: Metadata about the conversion (operation, filename, size, paper size, etc.)
Binary data: The PDF file (accessible via pdf key)

Using with Other Nodes

The Gotenberg node works well with:

HTTP Request: Fetch dynamic URLs
Code: Process the binary PDF data
Write Binary File: Save PDFs to disk
Email: Attach PDFs to emails
Google Drive: Upload PDFs to cloud storage

API Reference

The node uses multiple Gotenberg API endpoints:

Chromium Conversion:

URL to PDF: /forms/chromium/convert/url
HTML to PDF: /forms/chromium/convert/html

PDF Processing:

Merge PDFs: /forms/pdfengines/merge
Split PDF: /forms/pdfengines/split

For more details about available parameters, see the Gotenberg documentation.

Error Handling

The node provides comprehensive error handling:

Connection errors: When Gotenberg instance is unreachable
Invalid URLs: When the provided URL cannot be accessed
Conversion errors: When PDF generation fails
Timeout errors: When conversion takes too long

Enable "Continue on Fail" to handle errors gracefully in your workflow.

Development

To contribute to this node:

Clone the repository
Install dependencies: npm install
Build the project: npm run build
Test with your n8n instance

Note: During development, you might see TypeScript errors related to n8n-workflow module. This is expected in a development environment. The node will work correctly when installed in an actual n8n instance where the n8n-workflow package is available.

Building

npm run build

Linting

npm run lint
npm run lintfix  # Auto-fix issues

Formatting

npm run format

Changelog

1.1.0

New Operations: Added Merge PDFs and Split PDF operations
Enhanced HTML to PDF: Added support for additional files (images)
Advanced PDF Options: PDF/A conversion, PDF for Universal Access, flatten PDF
Improved UI: Better organization of advanced options
Multiple Output Types: Support for ZIP files (split operations)
Published to npm: Available as n8n-nodes-gotenberg-pdf

0.1.0

Initial release
URL to PDF conversion support
HTML to PDF conversion support
Standardized paper sizes (A4, Letter, Legal, A3, A5, Tabloid, Custom)
Advanced options collection for clean UI
Comprehensive margin and scaling controls
Binary PDF output with metadata
Error handling and continue-on-fail support

License

MIT License - see LICENSE.md for details.

Support

Gotenberg - The PDF conversion API
n8n - Workflow automation platform
n8n Community Nodes - Documentation for community nodes