Gotenberg Rails

Render Rails HTML as PDFs with Gotenberg.

To quickly try the gem locally, see the Gotenberg Rails example application.

Installation

Add the gem to your Gemfile:

gem "gotenberg-rails"

Run Gotenberg:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Usage

Render a PDF from a Rails controller:

def show
  respond_to do |format|
    format.html
    format.pdf do
      render gotenberg_pdf: {}, disposition: :inline, filename: "invoice.pdf"
    end
  end
end

Customize the rendered template and Gotenberg options:

def show
  render gotenberg_pdf: {
    print_background: true,
    paper_width: "8.27",
    paper_height: "11.7",
    margin_top: "0.4",
    margin_bottom: "0.4",
    margin_left: "0.4",
    margin_right: "0.4"
  },
  layout: "pdf",
  template: "invoices/show",
  disposition: :inline,
  filename: "invoice.pdf"
end

You can also render directly:

Gotenberg::Rails.render_pdf(html: html)
Gotenberg::Rails.render_pdf(html: html, display_url: "https://example.com/invoice")
Gotenberg::Rails.render_pdf(url: "https://example.com/invoice")

Add a header or footer to every page by passing complete HTML documents:

Gotenberg::Rails.render_pdf(
  html: html,
  header_html: "<html><body>Invoice</body></html>",
  footer_html: '<html><body>Page <span class="pageNumber"></span> of <span class="totalPages"></span></body></html>',
  pdf_options: {
    margin_top: "1in",
    margin_bottom: "1in"
  }
)

From a controller, Rails templates can be rendered separately for the header and footer:

header_html = render_to_string(template: "invoices/header", layout: false)
footer_html = render_to_string(template: "invoices/footer", layout: false)

render gotenberg_pdf: {
  header_html: header_html,
  footer_html: footer_html,
  margin_top: "1in",
  margin_bottom: "1in"
}, template: "invoices/show", layout: "pdf"

Header and footer templates must each be complete HTML documents. They are rendered separately from the main page, so JavaScript and external stylesheets or images are unavailable. Embed images as Base64 data URLs and leave enough top and bottom margin to avoid clipping.

When rendering HTML, display_url is used to rewrite relative image, link, JavaScript, stylesheet, and CSS url(...) references to absolute URLs before sending the HTML to Gotenberg. Controller rendering uses request.original_url automatically.

Options are sent to Gotenberg as Chromium form fields. Ruby-style snake case keys are converted to Gotenberg camel case keys:

Gotenberg::Rails.render_pdf(
  html: html,
  pdf_options: {
    print_background: true,
    emulated_media_type: "screen",
    wait_delay: "2s",
    fail_on_http_status_codes: [499, 599],
    metadata: { Title: "Invoice" }
  }
)

Configuration

Gotenberg::Rails.configure do |config|
  config.endpoint = ENV.fetch("GOTENBERG_ENDPOINT", "http://gotenberg:3000")
  config.open_timeout = 5
  config.request_timeout = 30
  config.headers = { "X-Request-Source" => "rails" }
  config.pdf_options = {
    print_background: true,
    prefer_css_page_size: true
  }
end

Gotenberg receives rendered HTML as an index.html upload. Use absolute URLs for stylesheets, images, and fonts that Gotenberg must fetch from your Rails app.

License

The gem is available as open source under the terms of the MIT License.

gotenberg-rails

Development

Runtime

Gotenberg Rails

Installation

Usage

Configuration

License