Skip to main content
Version: 7.x

Chromium

The Chromium module interacts with the Chromium browser to convert HTML documents to PDF.

info

It starts a dedicated Chromium instance for each request.

caution

The amd64 Docker image uses Google Chrome stable, while other architectures use an earlier version of Chromium.

Until Google or Debian packages' managers provide a more up-to-date version of Chromium for arm64, armhf, and i386 platforms, the Docker images will differ, alas.

Properties

--chromium-allow-file-access-from-files bool    Allow file:// URIs to read other file:// URIs
--chromium-allow-insecure-localhost bool Ignore TLS/SSL errors on localhost
--chromium-allow-list string Set the allowed URLs for Chromium using a regular expression
--chromium-deny-list string Set the denied URLs for Chromium using a regular expression (default "^file:///[^tmp].*")
--chromium-ignore-certificate-errors bool Ignore the certificate errors
--chromium-disable-web-security bool Don't enforce the same-origin policy
caution

--chromium-user-agent property is deprecated. Prefer the userAgent form field instead.

Routes

Each route accepts multipart/form-data requests.

They share the following form fields:

paperWidth        float   Paper width, in inches (default 8.5)
paperHeight float Paper height, in inches (default 11)
marginTop float Top margin, in inches (default 0.39)
marginBottom float Bottom margin, in inches (default 0.39)
marginLeft float Left margin, in inches (default 0.39)
marginRight float Right margin, in inches (default 0.39)
preferCssPageSize bool Define whether to prefer page size as defined by CSS (default false)
printBackground bool Print the background graphics (default false)
landscape bool Set the paper orientation to landscape (default false)
scale float The scale of the page rendering (default 1.0)
nativePageRanges string Page ranges to print, e.g., '1-5, 8, 11-13' - empty means all pages

For instance:

curl \
--request POST 'http://localhost:3000/forms/chromium/convert/url' \
--form 'url="https://my.url"' \
--form 'paperWidth="8.27"' \
--form 'paperHeight="11.7"' \
--form 'marginTop="1"' \
--form 'marginBottom="1"' \
--form 'marginLeft="1"' \
--form 'marginRight="1"' \
--form 'preferCssPageSize="false"' \
--form 'printBackground="true"' \
--form 'landscape="true"' \
--form 'scale="2.0"' \
--form 'nativePageRanges="1-5"' \
-o my.pdf
tip

Examples of paper size (width x height):

  • Letter - 8.5 x 11 (default)
  • Legal - 8.5 x 14
  • Tabloid - 11 x 17
  • Ledger - 17 x 11
  • A0 - 33.1 x 46.8
  • A1 - 23.4 x 33.1
  • A2 - 16.54 x 23.4
  • A3 - 11.7 x 16.54
  • A4 - 8.27 x 11.7
  • A5 - 5.83 x 8.27
  • A6 - 4.13 x 5.83

URL

POST /forms/chromium/convert/url

This route accepts a form field url with the URL of the page you want to convert to PDF.

For instance:

curl \
--request POST 'http://localhost:3000/forms/chromium/convert/url' \
--form 'url="https://my.url"' \
--form 'marginTop="0"' \
--form 'marginBottom="0"' \
--form 'marginLeft="0"' \
--form 'marginRight="0"' \
-o my.pdf
tip

When converting a website to PDF, you should remove all margins. If not, the resulting PDF might not contain all content from the page.


The form fields extraLinkTags and extraScriptTags (JSON format) allows you to add <link> and <script> HTML elements with remote paths.

For instance:

curl \
--request POST 'http://localhost:3000/forms/chromium/convert/url' \
--form 'url="https://my.url"' \
--form 'extraLinkTags="[{\"href\":\"https://my.cdn.css\"}]"' \
--form 'extraScriptTags="[{\"src\":\"https://my.cdn.js\"}]"' \
-o my.pdf
info

For <link> HTML elements, only the href attribute is available.

info

For <script> HTML elements, only the src attribute is available.

caution

<script> HTML elements are not added if JavaScript is disabled via --chromium-disable-javascript.

HTML

POST /forms/chromium/convert/html

This route accepts a file named index.html.

For instance:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My PDF</title>
</head>
<body>
<h1>Hello world!</h1>
</body>
</html>
curl \
--request POST 'http://localhost:3000/forms/chromium/convert/html' \
--form 'files=@"/path/to/index.html"' \
-o my.pdf

You may also send additional files, like images, fonts, stylesheets, and so on.

The only requirement is that their paths in the index.html file are on the root level.

For instance, this will work:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My PDF</title>
</head>
<body>
<h1>Hello world!</h1>
<img src="img.png" />
</body>
</html>

But this won't:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My PDF</title>
</head>
<body>
<h1>Hello world!</h1>
<img src="/foo/img.png" />
</body>
</html>
curl \
--request POST 'http://localhost:3000/forms/chromium/convert/html' \
--form 'files=@"/path/to/index.html"' \
--form 'files=@"/path/to/style.css"' \
--form 'files=@"/path/to/img.png"' \
--form 'files=@"/path/to/font.woff"' \
-o my.pdf
tip

Remote paths for images, fonts (e.g., Google Fonts), etc., works too.

info

See the Fonts chapter if you want to install fonts in the Docker image.

Markdown

POST /forms/chromium/convert/markdown

This route accepts a file named index.html plus markdown files.

It works like the HTML route but with access to a Go template function toHTML. It converts a markdown file's content to HTML.

For instance:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My PDF</title>
</head>
<body>
{{ toHTML "file.md" }}
</body>
</html>
curl \
--request POST 'http://localhost:3000/forms/chromium/convert/markdown' \
--form 'files=@"/path/to/index.html"' \
--form 'files=@"/path/to/file.md"' \
-o my.pdf

Metric

The Chromium module exposes the following metric:

  • {namespace}_chromium_active_instances_count - current number of active Chromium instances.

See Prometheus for more details.