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.
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'
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
,header
andfooter
-
goten_static_asset_path
will return the absolute path to the static assets inside theapp/assets/
based on the extension. -
goten_compiled_asset_path
will return the absolute path to the precompiled assets inside thepublic/assets
-
goten_asset_base64
will return the base64 encoded of the 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 includeinclude Gotenberg::Helper
-
Both
header
andfooter
have 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.html
file footer.html
CSS 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-color
andcolor
CSS properties require an additional-webkit-print-color-adjust: exact
CSS 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