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-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-user-agent                   string  Override the default User-Agent header--chromium-ignore-certificate-errors    bool    Ignore the certificate errors--chromium-incognito                    bool    Start Chromium with incognito mode--chromium-disable-routes               bool    Disable the routes

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)

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"' \-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.

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