SkillAgentSearch skills...

Jotenberg

A Java library that interacts with Gotenberg's different modules to convert a variety of document formats to PDF files.

GenerateConvertImprove

Install / Use

/learn @cherfia/Jotenberg
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

build licence

A lightweight Java library that interacts with Gotenberg's different routes to convert a variety of document formats to PDF files.

Table of Contents

  1. Getting Started
  2. Authentication
  3. Core Features
  4. Usage Example

Getting Started

Installation

Apache Maven

First, add the GitHub Packages repository to your pom.xml:


<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/cherfia/jotenberg</url>
    </repository>
</repositories>

Then add the dependency:


<dependency>
    <groupId>io.bitizens</groupId>
    <artifactId>jotenberg</artifactId>
    <version>2.2.0</version>
</dependency>

Note: You'll need to authenticate with GitHub Packages. Create a personal access token with read:packages permission and add it to your ~/.m2/settings.xml:


<settings>
    <servers>
        <server>
            <id>github</id>
            <username>YOUR_GITHUB_USERNAME</username>
            <password>YOUR_GITHUB_TOKEN</password>
        </server>
    </servers>
</settings>

Gradle

First, add the GitHub Packages repository to your build.gradle:

repositories {
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/cherfia/jotenberg")
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
            password = project.findProperty("gpr.token") ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

Then add the dependency:

implementation group: 'io.bitizens', name: 'jotenberg', version: '2.2.0'

Note: You'll need to authenticate with GitHub Packages. Create a personal access token with read:packages permission and set it as an environment variable GITHUB_TOKEN or as a Gradle property gpr.token.

Prerequisites

Before attempting to use Jotenberg, be sure you install Docker if you have not already done so.

After that, you can start a default Docker container of Gotenberg as follows:

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

Configuration

Jotenberg uses constructor-based configuration. Create an instance of Jotenberg class and pass your Gotenberg endpoint URL as a constructor parameter:

import io.bitizens.Jotenberg;

Jotenberg client = new Jotenberg("http://localhost:3000");

Authentication

Basic Authentication

Gotenberg introduces basic authentication support starting from version 8.4.0. Suppose you are running a Docker container using the command below:

docker run --rm -p 3000:3000 \
-e GOTENBERG_API_BASIC_AUTH_USERNAME=user \
-e GOTENBERG_API_BASIC_AUTH_PASSWORD=pass \
gotenberg/gotenberg:8.4.0 gotenberg --api-enable-basic-auth

To integrate this setup with Jotenberg, you need to configure the HTTP client with basic authentication. You can extend the Jotenberg class or configure the underlying HTTP client to include authentication headers.

Advanced Authentication

To implement advanced authentication or add custom HTTP headers to your requests, you can configure the underlying HTTP client used by Jotenberg. This allows you to pass additional headers, such as authentication tokens or custom metadata, with each API call.

For example, you can include a Bearer token for authentication along with a custom header by configuring the HTTP client:

import io.bitizens.Jotenberg;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.client.methods.HttpRequestBase;
import org.apache.http.HttpRequest;

// Create a custom HTTP client with authentication
CloseableHttpClient httpClient = HttpClients.custom()
        .addInterceptorFirst((HttpRequest request) -> {
            request.addHeader("Authorization", "Bearer " + token);
            request.addHeader("X-Custom-Header", "value");
        })
        .build();

// Note: Jotenberg currently uses an internal HTTP client.
// For advanced authentication, you may need to extend the class or modify the HTTPRequestManager.

Core Features

Jotenberg introduces different classes that serve as wrappers to Gotenberg's routes. These classes encompass methods featuring an input file parameter, such as html, header, footer, and markdown, capable of accepting inputs in the form of a File or List<File>.

Chromium

There are three different methods that come with the Jotenberg class (i.e. convert) which calls one of Chromium's Conversion routes to convert html and markdown files, or a url to a CloseableHttpResponse which contains the HttpEntity that holds the content of the converted PDF file.

Similarly, a new set of methods have been added to harness the recently introduced Gotenberg Screenshot routes. These methods include a single method called capture, which allows capturing full-page screenshots of html, markdown, and url.

URL

import io.bitizens.Jotenberg;
import io.bitizens.chromium.ChromiumPageProperties;
import io.bitizens.chromium.ChromiumOptions;
import org.apache.http.client.methods.CloseableHttpResponse;

Jotenberg client = new Jotenberg("http://localhost:3000");

ChromiumPageProperties pageProperties = new ChromiumPageProperties.Builder().build();
ChromiumOptions options = new ChromiumOptions.Builder().build();

CloseableHttpResponse response = client.convert(
        "https://www.example.com/",
        pageProperties,
        options
);

import io.bitizens.Jotenberg;
import io.bitizens.screenshots.ImageProperties;
import io.bitizens.screenshots.ScreenshotOptions;
import org.apache.http.client.methods.CloseableHttpResponse;

Jotenberg client = new Jotenberg("http://localhost:3000");

ImageProperties imageProperties = new ImageProperties.Builder()
        .addFormat("png")
        .addWidth(1920)
        .addHeight(1080)
        .build();

ScreenshotOptions screenshotOptions = new ScreenshotOptions.Builder().build();

CloseableHttpResponse response = client.capture(
        "https://www.example.com/",
        imageProperties,
        screenshotOptions
);

HTML

The only requirement is that the file name should be index.html.

import io.bitizens.Jotenberg;
import io.bitizens.chromium.ChromiumPageProperties;
import io.bitizens.chromium.ChromiumOptions;
import org.apache.http.client.methods.CloseableHttpResponse;

import java.io.File;

Jotenberg client = new Jotenberg("http://localhost:3000");

File file = new File("path/to/index.html");
ChromiumPageProperties pageProperties = new ChromiumPageProperties.Builder().build();
ChromiumOptions options = new ChromiumOptions.Builder().build();

CloseableHttpResponse response = client.convert(file, pageProperties, options);

import io.bitizens.Jotenberg;
import io.bitizens.screenshots.ImageProperties;
import io.bitizens.screenshots.ScreenshotOptions;
import org.apache.http.client.methods.CloseableHttpResponse;

import java.io.File;

Jotenberg client = new Jotenberg("http://localhost:3000");

File file = new File("path/to/index.html");
ImageProperties imageProperties = new ImageProperties.Builder()
        .addFormat("png")
        .build();
ScreenshotOptions screenshotOptions = new ScreenshotOptions.Builder().build();

CloseableHttpResponse response = client.capture(file, imageProperties, screenshotOptions);

Markdown

This route accepts an index.html file plus a markdown file.

import io.bitizens.Jotenberg;
import io.bitizens.chromium.ChromiumPageProperties;
import io.bitizens.chromium.ChromiumOptions;
import org.apache.http.client.methods.CloseableHttpResponse;

import java.io.File;
import java.util.ArrayList;
import java.util.List;

Jotenberg client = new Jotenberg("http://localhost:3000");

List<File> files = new ArrayList<>();
files.

add(new File("path/to/index.html"));
        files.

add(new File("path/to/file.md"));

ChromiumPageProperties pageProperties = new ChromiumPageProperties.Builder().build();
ChromiumOptions options = new ChromiumOptions.Builder().build();

CloseableHttpResponse response = client.convert(files, pageProperties, options);

import io.bitizens.Jotenberg;
import io.bitizens.screenshots.ImageProperties;
import io.bitizens.screenshots.ScreenshotOptions;
import org.apache.http.client.methods.CloseableHttpResponse;

import java.io.File;
import java.util.ArrayList;
import java.util.List;

Jotenberg client = new Jotenberg("http://localhost:3000");

List<File> files = new ArrayList<>();
files.

add(new File("path/to/index.html"));
        files.

add(new File("path/to/file.md"));

ImageProperties imageProperties = new ImageProperties.Builder()
        .addFormat("

cherfia

View profile

View on GitHub
GitHub Stars32
CategoryDevelopment
Updated1mo ago
Forks7
cherfia/jotenberg

Languages

Java

Security Score

95/100

Audited on Feb 25, 2026

No findings