HTML to PDF in Go

Overview

Convert web pages and HTML documents to PDF with the PDFCrowd Go client. The client handles communication with the API, while conversions run on PDFCrowd's servers.

Installation

Add the Go client to your module with go get, or see other installation options.

go get github.com/pdfcrowd/pdfcrowd-go

Quick Start

You can run the examples below with the displayed API credentials. Update the input URLs and filenames as needed.

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewHtmlToPdfClient("demo", "demo")

    client.SetContentViewportWidth("balanced")
    err := client.ConvertUrlToFile("https://example.com/", "example.pdf")
    checkError(err)
}

func checkError(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewHtmlToPdfClient("demo", "demo")

    client.SetContentViewportWidth("balanced")
    err := client.ConvertFileToFile("document.html", "document.pdf")
    checkError(err)
}

func checkError(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

Configure a Conversion

Authentication

Pass your PDFCrowd username and API key to NewHtmlToPdfClient. Find your credentials on the API Keys page.

To load a protected source website, configure its website credentials, cookies, or HTTP headers separately.

Choose an Input

URLs must be reachable from PDFCrowd's servers. For a page on localhost, send its HTML content or upload a file. Referenced assets must also be reachable from PDFCrowd's servers or included in an archive.

Send HTML Content

Convert an HTML string to PDF and save it as report.pdf:

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewHtmlToPdfClient("demo", "demo")

    html := `
        <!doctype html>
        <html><body><h1>Monthly report</h1></body></html>`

    client.SetContentViewportWidth("balanced")
    err := client.ConvertStringToFile(html, "report.pdf")
    checkError(err)
}

func checkError(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

Replace html with the output of your template renderer. For relative resource URLs, add a <base href="https://your-site.example/"> element to the HTML head, or use absolute URLs.

Replace https://your-site.example/ with your website's public URL. The <base> element tells PDFCrowd where to resolve relative URLs. For example, /static/style.css becomes https://your-site.example/static/style.css.

PDFCrowd can also combine an HTML template with structured data; see HTML templates.

Include Local Assets

Package the HTML and its local images, CSS, and JavaScript in a .zip, .tar.gz, or .tar.bz2 archive. Preserve the relative paths used by the HTML.

Convert the HTML document inside document.zip and save the PDF as output.pdf:

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewHtmlToPdfClient("demo", "demo")

    client.SetContentViewportWidth("balanced")
    err := client.ConvertFileToFile("document.zip", "output.pdf")
    checkError(err)
}

func checkError(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

The API automatically converts the first HTML file it finds in the archive. If the archive contains multiple HTML files, use SetZipMainFilename() to choose which one to convert.

Add Conversion Settings

Set conversion options on the client before calling a conversion method. For example, client.SetPageSize("A4") selects A4 paper.

Common settings are listed below. See the method reference for all available options, browse Go examples, or try settings in the API Playground.

Handle the Result

Choose an Output

The methods below use URL input; HTML strings and files have corresponding methods.

File-output methods overwrite an existing destination file.

This example converts a web page, receives the result as a []byte and saves it as example.pdf:

package main

import (
    "log"
    "os"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewHtmlToPdfClient("demo", "demo")

    result, err := client.ConvertUrl("https://example.com/")
    checkError(err)
    checkError(os.WriteFile("example.pdf", result, 0644))
}

func checkError(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

When serving the PDF from a web application, use Content-Type: application/pdf.

Handle Errors

Conversion methods return an error. API and validation errors have the type pdfcrowd.Error; local file and connection failures can return other error types. This example converts a web page, logs any error, and uses errors.As to read the HTTP status and reason code when available:

package main

import (
    "errors"
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewHtmlToPdfClient("demo", "demo")

    err := client.ConvertUrlToFile(
        "https://example.com/", "example.pdf",
    )
    checkError(err)
}

func checkError(err error) {
    if err != nil {
        var apiError pdfcrowd.Error
        if errors.As(err, &apiError) {
            log.Printf("Status: %d; reason: %d",
                apiError.GetStatusCode(), apiError.GetReasonCode())
        }
        log.Fatal(err)
    }
}

pdfcrowd.Error provides these methods:

Error() returns the complete error message, including available status and reason codes.

Common Status Codes

See all status and reason codes for specific explanations and Limits and Retries for retry behavior.

Read Conversion Information

This information is available after a conversion and describes the client's last conversion.

Limits and Retries

Request rate and concurrency limits depend on your license. Control how quickly your application submits conversions and how many it runs at once. A 429 response concerns request rate; a 430 response concerns requests already in progress. The maximum upload size is 300 MB.

The Go client automatically retries a request once when it receives HTTP 502 or 503. Use SetRetryCount() to change that count, or set it to 0 to disable automatic retries. Account for these retries when adding an application-level retry policy.

PDFCrowd stops a conversion that exceeds 60 seconds of processing time. Reason code 323 identifies this HTML conversion timeout. Check for slow resource downloads or long-running JavaScript. Allowing your application to wait longer does not extend the server's processing limit.

Troubleshooting

Inspect a Conversion

This example converts a web page with debug logging enabled and logs the debug log URL when available. Use the input and settings from the conversion you are investigating.

package main

import (
    "log"
    "github.com/pdfcrowd/pdfcrowd-go"
)

func main() {
    client := pdfcrowd.NewHtmlToPdfClient("demo", "demo")

    client.SetDebugLog(true)

    err := client.ConvertUrlToFile(
        "https://example.com/", "example.pdf",
    )
    if debugLogURL := client.GetDebugLogUrl(); debugLogURL != "" {
        log.Printf("Debug log: %s", debugLogURL)
    }
    checkError(err)
}

func checkError(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

The debug log includes resource-loading details, timeouts, and browser console messages. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.

Common Problems

For help, contact support and include any available diagnostics, the client version, and enough detail to reproduce the problem.