Can it render a URL instead of an HTML string?

Yes: send url instead of html. It must be a public https page, which is loaded without your cookies or headers; addresses in private networks are refused, and a page that does not load within 30 seconds fails with navigation_failed.

How large may the HTML be?

Up to 5 MB per request. Images and fonts are fetched by URL and do not count towards that. Limits per plan are in the docs.

Does JavaScript in the page run?

Yes, Chromium runs it before printing, which is how charts render. It waits until the network has been idle, for at most 30 seconds, so a page that keeps loading fails with render_timeout rather than hanging.

Guide · Ruby

Convert HTML to PDF in Ruby

Chromium makes the best HTML-to-PDF converter, and the worst dependency: hundreds of megabytes, fonts to install, zombie processes to reap. This Ruby program sends an HTML file to the Formfeed API instead and saves what Chromium prints.

Start for free Read the docs

Free plan with 100 units a month, no credit card

What you need

An API key. Create one in the app under API keys and export it as FORMFEED_API_KEY. A test key (ff_test_…) is right for trying things out. See the quick start.
Ruby. You need Ruby 3; the program uses net/http and json from the standard library.
An HTML file. invoice.html next to the program: a complete document with its CSS inline or linked. A sample is further down.

The program

The program reads invoice.html, posts it with the paper size and the margins, waits for the result when the API answers 202, stops with the API’s message when something is wrong, and saves the PDF.

render.rbRuby

require "json"
require "net/http"

body = {
  html: File.read("invoice.html"),
  settings: {
    paper: { format: "A4" },
    margin: { top: "20mm", right: "18mm", bottom: "20mm", left: "18mm" },
  },
}
auth = { "Authorization" => "Bearer #{ENV.fetch("FORMFEED_API_KEY")}" }

response = Net::HTTP.post(
  URI("https://api-eu.formfeed.dev/v1/renders"),
  JSON.generate(body),
  auth.merge("Content-Type" => "application/json")
)
render = JSON.parse(response.body)

# not done within 60 seconds: the answer is 202 and the render goes on in the background;
# its result answers the same way until the render has finished
while response.code == "202"
  sleep 2
  response = Net::HTTP.get_response(URI("https://api-eu.formfeed.dev/v1/renders/#{render["id"]}/result"), auth)
  render = JSON.parse(response.body)
end

# every error is a problem document (RFC 9457) with a title and a detail
abort "#{render["title"]}: #{render["detail"]}" unless response.is_a?(Net::HTTPSuccess)

File.binwrite("invoice.pdf", Net::HTTP.get(URI(render["download_url"])))
puts "#{render["id"]} #{render["page_count"]} page(s), #{render["units"]} unit(s)"

Run it

It prints the render’s id, the page count and the units it cost, and invoice.pdf lies next to the program.

Shell

export FORMFEED_API_KEY=ff_test_...
ruby render.rb

What is particular about Ruby

Hashes become JSON. Symbol keys are fine: JSON.generate writes them as strings, and the API’s snake_case names are idiomatic Ruby anyway.
abort with the problem. A problem document carries a title and a detail; the program prints both and exits with status 1.
In Rails. Put the call in a job (Active Job, Sidekiq), not in the request cycle: a synchronous render answers when the PDF is done, which can take up to 60 seconds before the API answers 202 and finishes in the background.

An HTML file that prints well

The HTML is printed as it is, with the print rules Chromium supports. Web fonts load from a <link>, and two CSS rules keep a long table readable across pages:

invoice.htmlHTML

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">
    <style>
      body { font-family: 'Inter', sans-serif; font-size: 10pt; color: #1e293b; }
      h1 { font-size: 20pt; color: #312e81; }
      table { width: 100%; border-collapse: collapse; }
      td, th { padding: 2mm; border-bottom: 1px solid #e2e8f0; text-align: left; }
      thead { display: table-header-group; } /* repeats the head row on every page */
      tr { break-inside: avoid; }
    </style>
  </head>
  <body>
    <h1>Invoice 2026-0042</h1>
    <table>
      <thead><tr><th>Item</th><th>Amount</th></tr></thead>
      <tbody><tr><td>Consulting</td><td>960.00 €</td></tr></tbody>
    </table>
  </body>
</html>

What the settings control

Paper. paper.format takes A4, Letter and the other common names, landscape: true turns it, and width with height sets a custom size such as a 100 × 150 mm label.
Margins. Per side, as CSS lengths such as 20mm. A background that should reach the edge needs margins of 0.
Header and footer. header.html and footer.html repeat on every page inside the top and bottom margin; elements with the classes pageNumber and totalPages show the page numbers.
Placeholders. Add "engine": "jinja2" (or liquid, handlebars) and a data object, and {{ … }} in the HTML is filled before printing, with all helpers for money, dates, barcodes and charts.

When a template is the better tool

Sending HTML is right for pages your application already renders. When the document is yours to design (invoices, certificates, reports), a stored template gives you an editor with a page-accurate preview, versions, and a request that carries only data. The PDF invoice guide of this language shows that variant.

When the API says no

One shape for every error. Errors are problem documents (RFC 9457) with type, title, status, detail, a stable code and the request_id to quote to support; the type URL leads to a page about that error. The list is in the error reference.
The usual ones. 401 unauthorized for a missing or revoked key, 404 template_not_found for a wrong template name, 422 template_runtime_error when the template fails on the data, 429 rate_limited above the plan’s requests per second, 402 quota_exceeded when the Free plan’s units are used up (a paid plan bills extra units up to its hard cap).
Retry safely. Send an Idempotency-Key header with the POST, and repeat the request with the same key when you do not know whether the first attempt arrived: for 24 hours the key returns the first answer instead of rendering and billing again. The answer is stored once the first attempt has been answered, so do not retry while it may still run; and problems below 500 are stored too, so a corrected request needs a new key.

The job around this program

This guide is one program. What the job needs around it, from the template to the limits and the price, is on the page HTML to PDF API.

More Ruby guides

FAQ

Can it render a URL instead of an HTML string?: Yes: send url instead of html. It must be a public https page, which is loaded without your cookies or headers; addresses in private networks are refused, and a page that does not load within 30 seconds fails with navigation_failed.
How large may the HTML be?: Up to 5 MB per request. Images and fonts are fetched by URL and do not count towards that. Limits per plan are in the docs.
Does JavaScript in the page run?: Yes, Chromium runs it before printing, which is how charts render. It waits until the network has been idle, for at most 30 seconds, so a page that keeps loading fails with render_timeout rather than hanging.