Generate PDF files from HTML, Markdown, Word or Excel using Gotenberg

Turn HTML, Markdown, Word, or Excel sources into polished PDF documents by orchestrating the Gotenberg conversion API from Kestra. Gotenberg is a stateless, Docker-based service that wraps Chromium and LibreOffice behind a simple HTTP interface, so you get reliable, server-side PDF rendering without bundling a headless browser into your own application. This blueprint shows the smallest possible end-to-end pattern: post a source URL to Gotenberg and capture the rendered PDF as a Kestra output file, ready to store, email, or hand off to downstream tasks.

How it works

The flow defines two variables: server, pointing at a Gotenberg instance (the public https://demo.gotenberg.dev demo by default), and template, the URL of the HTML page to render. A single pdf task of type io.kestra.plugin.scripts.shell.Commands runs on the io.kestra.plugin.core.runner.Process task runner. It issues a curl POST to the /forms/chromium/convert/url Gotenberg endpoint, passing the template URL as a form field and writing the response to myfile.pdf. That filename is declared in outputFiles, so Kestra captures the generated PDF in internal storage and exposes it as a downloadable execution output.

What you get

• A rendered myfile.pdf captured as a Kestra output file on every run.
• A reusable, declarative pattern for any Gotenberg conversion route.
• Server-side rendering with no headless browser to manage in your code.
• A demo-ready flow that works against the public Gotenberg endpoint out of the box.

Who it's for

• Data and platform engineers automating invoice, report, or statement generation.
• Backend teams that need PDF rendering as a pipeline step rather than an app dependency.
• Anyone evaluating Gotenberg who wants a working Kestra example to copy.

Why orchestrate this with Kestra

Gotenberg is a conversion service, not a scheduler: it renders what you send it and nothing more. Kestra supplies the orchestration layer around it. You can drive conversions from schedule or event triggers, add automatic retries when the API is briefly unavailable, fan out across many documents, and chain the PDF into downstream tasks such as uploading to object storage or sending an email. Every run is captured with full lineage and logs, and the whole pipeline stays declarative YAML you can version and review.

Prerequisites

• A reachable Gotenberg server. Start one locally with docker run --rm -p 3000:3000 gotenberg/gotenberg:7, then set server to your instance, or keep the bundled https://demo.gotenberg.dev demo for testing.
• curl available on the worker (it ships with the Process runner environment used here).

Secrets

This blueprint references no Kestra secrets. The default demo endpoint is public; if your Gotenberg instance requires authentication, add a header to the curl command and store the credential with {{ secret('GOTENBERG_TOKEN') }}.

Quick start

1. Add the blueprint to your Kestra instance.
2. Set the server variable to your Gotenberg URL, or leave the demo default.
3. Set template to the page you want to convert.
4. Execute the flow and download myfile.pdf from the execution outputs.

How to extend

• Swap the Chromium URL route for /forms/libreoffice/convert to turn Word or Excel files into PDFs.
• Convert raw HTML or Markdown by uploading files as form fields instead of a URL.
• Add a schedule trigger to generate documents on a recurring cadence.
• Follow the pdf task with a storage upload or notification task to deliver the result.

Links

• Scripts plugin documentation
• Gotenberg documentation