gotenberg

According to the official documentation, Gotenberg is a Docker-powered stateless API for PDF files. It offers a developer-friendly API that utilizes powerful tools like Chromium and LibreOffice to convert various document formats (such as HTML, Markdown, Word, Excel, and more) into PDF files and beyond. The gotenberg gem is a simple Ruby client for interacting with this API. Gotenberg provides multiple APIs for tasks such as converting HTML to PDF, URL to PDF, Markdown to PDF, and more.

Currently, this gem only supports the HTML conversion to PDF and health endpoint APIs. This gem seamlessly integrates the Rails asset pipeline with Gotenberg's requirements for HTML and assets and includes useful helper methods for assets which can be used in .erb files or other Ruby classes.

Please note that Gotenberg needs to be deployed on your server or VPC and can function as a stateless, central PDF generation engine for all of your applications. For more information and installation guides, please visit the official website.

High-level flow diagram:

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add gotenberg

If bundler is not being used to manage dependencies, install the gem by executing:

gem install gotenberg

In your Gemfile

gem 'gotenberg'

Usage

    client = Gotenberg::Client.new(ENV.fetch('GOTENBERG_ENDPOINT', nil))
    htmls = {
        index: "<h1> Body Html String </h1>",
        header: "<h1> Header Html String </h1>",
        footer: "<h1> Footer Html String </h1>"
    }

    asset_paths = [
        goten_static_asset_path('logo.svg'),
        goten_static_asset_path('gotenberg.png'),
        goten_compiled_asset_path('pdf/pdf.css'),
        goten_compiled_asset_path('pdf/pdf.js')
    ]
    properties = {
        paperWidth: '8.27',
        paperHeight: '11.7',
        marginTop: 10,
        marginBottom: 15,
        marginLeft: 10,
        marginRight: 10
        preferCssPageSize: false,
        printBackground: false,
        omitBackground: false,
        landscape: false,
        scale: 1.0
      }
    # All the properties supported by the gotenberg can be a property. Check official gotenberg docs for more info
    pdf_content = client.html(htmls, asset_paths, properties)

Important Notes:

The keys must be exactly index, header and footer
goten_static_asset_path will return the absolute path to the static assets inside the app/assets/ based on the extension.
goten_compiled_asset_path will return the absolute path to the precompiled assets inside the public/assets
goten_asset_base64 will return the base64 encoded of the assets.
goten_static_asset_base64 will return the base64 encoded of the static assets.
All these methods will be available automatically in the .erb files but if you need in the .rb files, then you will need to include include Gotenberg::Helper

Both header and footer have to be a complete HTML document

header.html

<html>
  <head> </head>
  <body>
    <h1>Header</h1>
  </body>
</html>

footer.html

<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

Header and Footer Limitations(source):
1. JavaScript is not executed
2. external resources are not loaded
3. the CSS properties are independant of the ones used in the index.html file
4. footer.html CSS properties override the ones from header.html
5. only fonts installed in the Docker image are loaded (see the fonts section)
6. images only work using a base64 encoded source (<img src="data:image/png;base64, iVBORw0K... />)
7. background-color and color CSS properties require an additional -webkit-print-color-adjust: exact CSS property in order to work
Basic Authentication
1. GOTENBERG_ENDPOINT='http://localhost:3000'
2. GOTENBERG_API_BASIC_AUTH_USERNAME='username'
3. GOTENBERG_API_BASIC_AUTH_PASSWORD='password'
Fonts
1. Use Base64 encoding so that the font file is embedded directly in the CSS file, eliminating the need for an external font file.
```
   Example:
   @font-face {
     font-family: "AvenirNextLTPro-Regular";
     src: url('AvenirNextLTPro-Regular.otf?base64, <base64_font_data>') format('opentype');
    }
```
2.Use goten_static_asset_path to generates a URL or path to the static version of the fonts, typically in its original form without any modifications from the build process.
```
   Example:
   goten_static_asset_path('AvenirNextLTPro-Regular.otf'),
```
Styling
1. By default, Pdf Layout has 1 inch margin in all the sides, to modify use @page css property.
```
   Example:
   @page {
    margin-top: 100px;
    margin-bottom: 60px;
   }
```
1. For different pdf if you need different layout and styling, make multiple scss or css files for each pdf.
```
  Example:
  goten_compiled_asset_path('pdf/pdf1.css'),
goten_compiled_asset_path('pdf/pdf2.css'),
```

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/SELISEdigitalplatforms/gotenberg.git

gotenberg

Runtime

gotenberg

Installation

Usage

Important Notes:

Contributing