Skip to main content
Version: 6.x

HTML

Gotenberg provides the endpoint /convert/html for HTML conversions.

It accepts POST requests with a multipart/form-data Content-Type.

Basic​

The only requirement is to send a file named index.html: it is the file which will be converted to PDF.

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 \
     --url http://localhost:3000/convert/html \
     --header 'Content-Type: multipart/form-data' \
     --form files=@index.html \
     -o result.pdf

You may also add a header and/or a footer in the resulting PDF. Respectively, a file named header.html and footer.html.

Each of them has to be a complete HTML document:

<html>
  <head>
    <style>
      body {
        font-size: 8rem;
        margin: 4rem auto;
      }
    </style>
  </head>
  <body>
    <p><span class="pageNumber"></span> of <span class="totalPages"></span></p>
  </body>
</html>

The following classes allow you to inject printing values:

  • date: formatted print date
  • title: document title
  • pageNumber: current page number
  • totalPage: total pages in the document

There are some limitations:

  • JavaScript is not executed
  • external resources are not loaded
  • the CSS properties are independant of the ones used in the index.html file
  • footer.html CSS properties override the ones from header.html
  • only fonts installed in the Docker image are loaded (see the fonts section)
  • images only work using a base64 encoded source (<img src="data:image/png;base64, iVBORw0K... />)
  • background-color and color CSS properties require an additional -webkit-print-color-adjust: exact CSS property in order to work
curl --request POST \
     --url http://localhost:3000/convert/html \
     --header 'Content-Type: multipart/form-data' \
     --form files=@index.html \
     --form files=@header.html \
     --form files=@footer.html \
     -o result.pdf

Assets​

You may also send additional files. For instance: images, fonts, stylesheets and so on.

The only requirement is to make sure that their paths are on the same level as the index.html file.

In other words, 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>

You may also use remote paths for Google fonts, images and so on.

info

If you want to install fonts directly in the Gotenberg Docker image, see to the fonts section.

curl --request POST \
     --url http://localhost:3000/convert/html \
     --header 'Content-Type: multipart/form-data' \
     --form files=@index.html \
     --form files=@style.css \
     --form files=@img.png \
     --form files=@font.woff \
     -o result.pdf

Paper size, margins, orientation, scaling​

You may also customize the resulting PDF format.

By default, it will be rendered with A4 size, 1 inch margins and portrait orientation and 100% (1.0) page scale.

caution

Paper size and margins have to be provided in inches. Same for margins.

curl --request POST \
     --url http://localhost:3000/convert/html \
     --header 'Content-Type: multipart/form-data' \
     --form files=@index.html \
     --form files=@style.css \
     --form files=@img.png \
     --form files=@font.woff \
     -o result.pdf

Page ranges​

You may specify the page ranges to convert.

The format is the same as the one from the print options of Google Chrome, e.g. 1-5,8,11-13.

curl --request POST \
     --url http://localhost:3000/convert/html \
     --header 'Content-Type: multipart/form-data' \
     --form files=@index.html \
     --form pageRanges='1-3,5' \
     -o result.pdf

Wait delay​

In some cases, you may want to wait a certain amount of time to make sure the page you're trying to generate is fully rendered. For instance, if your page relies a lot on JavaScript for rendering.

caution

The wait delay is a duration in seconds (e.g 2.5 for 2.5 seconds).

curl --request POST \
     --url http://localhost:3000/convert/html \
     --header 'Content-Type: multipart/form-data' \
     --form files=@index.html \
     --form waitDelay=5.5 \
     -o result.pdf

Rpcc buffer size​

The API might return a 400 HTTP code with the message increase the Google Chrome rpcc buffer size.

If so, you may increase this buffer size with a form field named googleChromeRpccBufferSize.

It takes an int as value (e.g. 1048576 for 1 MB). The hard limit is 100 MB and is defined by Google Chrome itself.

tip

You may also define this value globally: see the environment variables section.

curl --request POST \
     --url http://localhost:3000/convert/html \
     --header 'Content-Type: multipart/form-data' \
     --form files=@index.html \
     --form googleChromeRpccBufferSize=1048576 \
     -o result.pdf