gotenberg

gotenberg-client

A high-performance Go client for the Gotenberg HTTP API with a fluent interface. Built using only the Go standard library (via http-client).

Features:

• Minimal dependencies (only stdlib + http-client)
• Fluent API for building requests
• Support for HTML/URL/Markdown to PDF conversion
• Support for Office documents (Word, Excel, PowerPoint, etc.) to PDF conversion
• PDF manipulation: merge, split, flatten, convert to PDF/A & PDF/UA, read/write metadata
• Screenshot generation for web pages and HTML content
• Webhook support
• Download from URLs support
• Request tracing support
• Easy file/multipart uploads
• Paper size, margins, and advanced PDF options

Quick Start: Synchronous HTML to PDF

See examples/cmd/chromium/helloworld for a basic HTML to PDF conversion example.

go run ./examples/cmd/chromium/helloworld

Markdown to PDF Conversion

Convert Markdown files to PDF with custom HTML templates. See examples/cmd/chromium/markdown for a complete example.

go run ./examples/cmd/chromium/markdown

Office Documents to PDF

Convert Office documents (Word, Excel, PowerPoint, etc.) to PDF. See examples/cmd/libreoffice/convert for a basic example.

go run ./examples/cmd/libreoffice/convert

Request Tracing

Gotenberg supports request tracing for better observability and debugging. By default, Gotenberg assigns a unique UUID trace to every request. You can also specify a custom trace identifier using the Trace() method:

resp, err := client.Chromium().
    ConvertHTML(context.Background(), htmlReader).
    Trace("my-custom-trace-12345").
    Send()

// The trace ID is returned in the response
log.Printf("Request trace: %s", resp.GotenbergTrace)

See examples/cmd/chromium/trace for a complete example.

Example: Async PDF Generation with Webhook

See examples/cmd/chromium/webhook for a full async webhook demo (HTML invoice to PDF, with logo, webhook server, and error handling).

# Run webhook example
go run ./examples/cmd/chromium/webhook

This will:

• Start a local webhook server
• Generate an invoice PDF using HTML template and logo
• Receive the PDF via webhook callback from Gotenberg

Installation

go get github.com/nativebpm/gotenberg-client

Basic Usage

See the examples in examples/ for complete usage demonstrations:

• examples/cmd/chromium/helloworld — Basic HTML to PDF
• examples/cmd/chromium/markdown — Markdown to PDF
• examples/cmd/chromium/webhook — Async webhook demo
• examples/cmd/chromium/downloadfrom — Download from URL example
• examples/cmd/chromium/trace — Request tracing example
• examples/cmd/libreoffice/convert — Office to PDF
• examples/cmd/libreoffice/downloadfrom — Download Office documents from URL
• examples/cmd/pdfengines/merge — PDF merge

Testing

Run all tests and benchmarks:

go test -v -bench=. ./...

Project Structure

• gotenberg.go — main client with module accessors
• chromium/ — Chromium module for HTML/URL/Markdown to PDF and screenshots
• libreoffice/ — LibreOffice module for Office documents to PDF
• pdfengines/ — PDF Engines module for PDF manipulation (merge, split, flatten, PDF/A, metadata)
• examples/ — real-world usage examples
• examples/cmd/chromium/helloworld — basic HTML to PDF conversion
• examples/cmd/chromium/markdown — markdown to PDF conversion
• examples/cmd/chromium/webhook — async webhook demo
• examples/cmd/chromium/downloadfrom — download from URL example
• examples/cmd/chromium/trace — request tracing example
• examples/cmd/libreoffice/convert — Office document to PDF conversion
• examples/cmd/libreoffice/downloadfrom — download Office documents from URL
• examples/cmd/pdfengines/merge — PDF merge example
• examples/model — invoice data structs
• examples/pkg/templates/invoice — HTML template for invoice
• examples/pkg/templates/markdown — HTML template for markdown
• examples/pkg/image — logo generator

Dependencies

• Go standard library
• github.com/nativebpm/http-client

No third-party dependencies are required, ensuring minimal bloat and maximum compatibility.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.