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:

1. Install n8n (if not already installed):

   npm install n8n -g

2. Install this community node:

   npm install n8n-nodes-gotenberg-pdf

3. 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:

1. Go to Credentials in your n8n instance
2. Create new credentials of type Gotenberg API
3. 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

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

HTML to PDF Conversion

1. Add the Gotenberg node to your workflow
2. Select "HTML to PDF" operation
3. Enter or paste your HTML content in the editor
4. Choose paper size and orientation
5. 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:

1. Select your preferred paper size or choose "Custom Size"
2. Enable landscape mode if needed
3. 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:

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. 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 Documentation
• n8n Community
• GitHub Issues

Related

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