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:
Install the gem and add to the application's Gemfile by executing:
bundle add gotenbergIf bundler is not being used to manage dependencies, install the gem by executing:
gem install gotenbergIn your Gemfile
gem 'gotenberg' 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)-
The keys must be exactly
index,headerandfooter -
goten_static_asset_pathwill return the absolute path to the static assets inside theapp/assets/based on the extension. -
goten_compiled_asset_pathwill return the absolute path to the precompiled assets inside thepublic/assets -
goten_asset_base64will return the base64 encoded of the assets. -
All these methods will be available automatically in the
.erbfiles but if you need in the.rbfiles, then you will need to includeinclude Gotenberg::Helper -
Both
headerandfooterhave to be a complete HTML documentheader.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 datetitle: document titlepageNumber: current page numbertotalPage: total pages in the document
-
Header and Footer Limitations(source):
- JavaScript is not executed
- external resources are not loaded
- the CSS properties are independant of the ones used in the
index.htmlfile footer.htmlCSS properties override the ones fromheader.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-colorandcolorCSS properties require an additional-webkit-print-color-adjust: exactCSS property in order to work
-
Basic Authentication
GOTENBERG_ENDPOINT='http://localhost:3000'GOTENBERG_API_BASIC_AUTH_USERNAME='username'GOTENBERG_API_BASIC_AUTH_PASSWORD='password'
Bug reports and pull requests are welcome on GitHub at https://github.com/SELISEdigitalplatforms/gotenberg.git