n8n-nodes-gotenberg-pdf/README.md

n8n community node for Gotenberg PDF conversion API

![Banner image](https://user-images.githubusercontent.com/10284570/173569848-c624317f-42b1-45a6-ab09-f0ea3c247648.png)

# n8n-nodes-gotenberg-pdf

This is an n8n community node for [Gotenberg](https://gotenberg.dev/), 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):
   ```bash
   npm install n8n -g
   ```

2. Install this community node:
   ```bash
   npm install n8n-nodes-gotenberg-pdf
   ```

3. Start n8n:
   ```bash
   n8n start
   ```

## Prerequisites

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

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

Or with custom configuration:
```bash
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](https://gotenberg.dev/docs).

## 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

```bash
npm run build
```

### Linting

```bash
npm run lint
npm run lintfix  # Auto-fix issues
```

### Formatting

```bash
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](LICENSE.md) for details.

## Support

- [Gotenberg Documentation](https://gotenberg.dev/docs)
- [n8n Community](https://community.n8n.io/)
- [GitHub Issues](https://github.com/your-username/n8n-nodes-gotenberg/issues)

## Related

- [Gotenberg](https://gotenberg.dev/) - The PDF conversion API
- [n8n](https://n8n.io/) - Workflow automation platform
- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/) - Documentation for community nodes