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
--chromium-incognito                    bool    Start Chromium with incognito mode
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)
omitBackground    bool    Hide the default white background and allow generating PDFs with transparency (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 'omitBackground="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
info

The rules regarding the printBackground and omitBackground form fields are the following:

  • If printBackground is set to false, no background is printed.
  • If printBackground is set to true:
    • If the HTML document has a background, that background is used.
    • If not:
      • If omitBackground is set to true, the default background is transparent.
      • If not, the default white background is used.

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

Health Check​

If --chromium-failed-starts-threshold=0, there is no health check.

The health route returns a 503 Service Unvailable response if the failed starts threshold has been reached.

Metric​

The Chromium module exposes the following metric:

  • {namespace}_chromium_active_instances_count - current number of active Chromium instances.
  • {namespace}_chromium_failed_starts_count - current number of Chromium consecutive starting failures.

See Prometheus for more details.

Troubleshooting​

PDF files size too large​

Using webfonts significantly increases the PDF file size. When using a custom font, see the Fonts chapter on how to install them in the Docker container instead. See issue #521 for more details.