In this guide you will learn how to convert HTML to PDF in Ruby using the HTML2PDF REST API. We will cover:

  • Converting a URL to PDF with Ruby
  • Converting raw HTML to PDF
  • Setting page size, orientation and layout options
  • Handling errors and status codes

The HTML2PDF API accepts both URLs and HTML and returns the generated PDF as the HTTP response. You call https://api.html2pdf.co.uk/ with your license key and parameters.

Prerequisites

  • Ruby 2.7 or later
  • The standard net/http and uri libraries (included with Ruby)
  • An HTML2PDF license key

1. Convert a URL to PDF in Ruby

First we will convert a public URL to a PDF file by sending a GET request to the API with the license and url parameters. 

require 'net/http'
require 'uri'

ENDPOINT    = 'https://api.html2pdf.co.uk/'.freeze
LICENSE_KEY = 'yourlicensekey'.freeze

def url_to_pdf(source_url, output_path)
  uri = URI(ENDPOINT)
  params = { license: LICENSE_KEY, url: source_url }
  uri.query = URI.encode_www_form(params)

  response = Net::HTTP.get_response(uri)

  unless response.is_a?(Net::HTTPSuccess)
    raise "HTML2PDF API error: HTTP #{response.code} #{response.message}"
  end

  File.open(output_path, 'wb') do |file|
    file.write(response.body)
  end
end

if __FILE__ == $0
  url_to_pdf('https://example.com', 'ruby-example.pdf')
  puts 'PDF created.'
end

This script fetches the PDF from the API and writes it to ruby-example.pdf.

2. Convert raw HTML to PDF in Ruby

If you render HTML templates in Ruby (for example in Rails or Sinatra) you can send the HTML directly to the API using a POST request with the html parameter. 

require 'net/http'
require 'uri'

ENDPOINT    = 'https://api.html2pdf.co.uk/'.freeze
LICENSE_KEY = 'yourlicensekey'.freeze

def html_to_pdf(html, output_path)
  uri = URI(ENDPOINT)

  form_data = {
    'license' => LICENSE_KEY,
    'html'    => html
  }

  request = Net::HTTP::Post.new(uri)
  request.set_form_data(form_data)

  response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
    http.request(request)
  end

  unless response.is_a?(Net::HTTPSuccess)
    raise "HTML2PDF API error: HTTP #{response.code} #{response.message}"
  end

  File.open(output_path, 'wb') do |file|
    file.write(response.body)
  end
end

if __FILE__ == $0
  html = '<html><body><h1>Hello from Ruby</h1><p>Converted with HTML2PDF.</p></body></html>'
  html_to_pdf(html, 'ruby-html.pdf')
  puts 'PDF created from HTML.'
end

This method is ideal when the HTML is not publicly accessible or is generated dynamically.

3. Setting conversion options

You can control the PDF output with additional parameters. Some of the most commonly used options are:

  • page_size (for example A4 or Letter)
  • orientation (portrait or landscape)
  • css_media_type (screen or print)
  • lazy_load and wait_time for JavaScript-heavy pages
require 'net/http'
require 'uri'

ENDPOINT    = 'https://api.html2pdf.co.uk/'.freeze
LICENSE_KEY = 'yourlicensekey'.freeze

def url_to_pdf_with_options(source_url, output_path)
  uri = URI(ENDPOINT)

  params = {
    license:        LICENSE_KEY,
    url:            source_url,
    page_size:      'A4',
    orientation:    'landscape',
    css_media_type: 'print',
    lazy_load:      'true',
    wait_time:      '3000'
  }

  uri.query = URI.encode_www_form(params)

  response = Net::HTTP.get_response(uri)

  unless response.is_a?(Net::HTTPSuccess)
    raise "HTML2PDF API error: HTTP #{response.code} #{response.message}"
  end

  File.open(output_path, 'wb') do |file|
    file.write(response.body)
  end
end

For a complete list of options, including headers, footers and watermarks, see the HTML2PDF API documentation.

Tip: Set your default layout options (page size, margins, header/footer, etc.) once in the members area. You can then keep your Ruby code very simple and override options only when needed.

4. Handling Errors

If something goes wrong the API responds with an HTTP status code instead of a PDF. Important codes include:

CodeDescription
200 OKConversion succeeded and the response body contains the PDF
400 Bad RequestNo URL or HTML was provided
401 Authorization requiredMissing or invalid license key
429 Too Many RequestsYou exceeded the limits of your plan
504 / 599Timeout or connectivity problems when fetching the URL

In Ruby you can inspect response.code and response.body and handle errors appropriately, for example by logging or retrying if it was a timeout.

5. Next Steps

You now know how to convert HTML to PDF in Ruby using the HTML2PDF API. From here you can: