paper

Paper

Paper is a Go library for creating PDF documents from HTML and structured components.

Use it when you want a direct HTML-to-PDF path, or when you need programmatic layout with rows, columns, headers, footers, metrics, tests, and explicit control over document generation.

Installation

go get github.com/avdoseferovic/paper

The structure assertion helper ships with the root module and adds no third-party dependencies — import github.com/avdoseferovic/paper/pkg/test directly.

HTML to PDF

For HTML-only documents, use paper.FromHTML.

package main

import (
	"context"
	"log"

	"github.com/avdoseferovic/paper"
)

func main() {
	doc, err := paper.FromHTML(context.Background(), `<h1>Hello</h1><p>World</p>`)
	if err != nil {
		log.Fatal(err)
	}

	if err := doc.Save("out.pdf"); err != nil {
		log.Fatal(err)
	}
}

All generation entry points take a context.Context as their first argument, so long-running conversions can be canceled or given deadlines.

Use paper.FromHTMLReader when the source HTML is already available as an io.Reader. For advanced HTML options such as asset base directories, call pkg/html directly and add the returned rows to a paper.New(...) document.

For mixed layouts, HTML fragments can also be used as regular components via github.com/avdoseferovic/paper/pkg/components/html:

htmlBlock, err := htmlcomponent.New(context.Background(), `<h2>Terms</h2><p>Rendered from HTML.</p>`)
if err != nil {
	log.Fatal(err)
}

doc := paper.New()
doc.AddAutoRow(
	col.New(6).Add(text.New("Direct Paper component")),
	col.New(6).Add(htmlBlock),
)

Component Layout

Use the row and column API when a document needs manual layout, repeated headers or footers, generated pages, metrics, or a testable component tree.

package main

import (
	"context"
	"log"

	"github.com/avdoseferovic/paper"
	"github.com/avdoseferovic/paper/pkg/components/col"
	htmlcomponent "github.com/avdoseferovic/paper/pkg/components/html"
	"github.com/avdoseferovic/paper/pkg/components/row"
	"github.com/avdoseferovic/paper/pkg/components/text"
	"github.com/avdoseferovic/paper/pkg/config"
	"github.com/avdoseferovic/paper/pkg/props"
)

func main() {
	cfg := config.NewBuilder().
		WithLeftMargin(15).
		WithTopMargin(15).
		Build()

	doc := paper.New(cfg)
	htmlBlock, err := htmlcomponent.New(context.Background(), `<p>HTML fragment inside the grid</p>`)
	if err != nil {
		log.Fatal(err)
	}

	doc.AddRows(
		row.New(12).Add(
			col.New(12).Add(text.New("Invoice", props.Text{Size: 18})),
		),
		row.New().Add(
			col.New(6).Add(text.New("Programmatic content")),
			col.New(6).Add(htmlBlock),
		),
		text.NewRow(8, "Generated with Paper"),
	)

	pdf, err := doc.Generate(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	if err := pdf.Save("invoice.pdf"); err != nil {
		log.Fatal(err)
	}
}

Paper uses a grid-based layout model. Rows stack vertically, columns split a row across the configured grid width (12 columns by default, configurable with WithMaxGridSize), and new pages are added automatically when content exceeds the useful page area after margins, headers, and footers are reserved.

Key Features

• HTML-to-PDF conversion through paper.FromHTML, paper.FromHTMLReader, and pkg/html — including @page size/margins and repeating top-level <header>/<footer> bands.
• Programmatic PDF layout with rows, columns, text, images, codes, tables, signatures, page numbers, headers, and footers.
• PDF outline bookmarks via props.Outline (and auto-generated from HTML headings with WithOutlineFromHeadings), preserved in every generation mode.
• Per-page text watermarks via config.WithWatermark.
• Document output as bytes, base64, saved files, or merged PDFs (see Merging PDFs for limitations).
• PDF permission protection for casual copy/print deterrence, not confidentiality-grade encryption. RC4 is the compatibility default; AES-128 is available with WithProtectionAlgorithm.
• Component-tree inspection through GetStructure, designed for deterministic unit tests.
• Optional generation metrics through decorator.NewMetrics.
• Internal PDF backend ownership, so application code depends on Paper's public packages rather than a third-party renderer API.

Merging PDFs

merge.Bytes (package pkg/merge) concatenates the pages of multiple PDFs into one document. It is designed for PDFs produced by Paper itself and has two hard limitations for external input:

• Encrypted PDFs are not supported. Password-protected input returns an error; decrypt before merging.
• Cross-reference streams are not supported. Many modern tools emit PDFs with xref streams (PDF 1.5+ compressed object streams); those inputs are rejected. Re-save such files with a classic xref table first.

Performance

Generation is benchmarked in benchmark_test.go. Two benchmarks live there:

• BenchmarkPDFGeneration — representative documents (text-heavy, mixed components, HTML translation, full HTML demo).
• BenchmarkPDFScaling — a text document swept across 10–1000 rows to expose the per-row / per-page cost curve.

Run them with:

# Representative scenarios
go test -run='^$' -bench=BenchmarkPDFGeneration -benchmem -count=6 .

# Size scaling curve
go test -run='^$' -bench=BenchmarkPDFScaling -benchmem -count=6 .

The numbers below are the median of 6 checked runs on an Apple M1 Pro (Go 1.26.4), single-threaded. They are representative of the bundled fixtures, not a universal guarantee — actual time scales with page count, image size, and component mix.

Representative documents (BenchmarkPDFGeneration)

Size scaling (BenchmarkPDFScaling)

The curve is linear, giving a simple cost model for text content:

time(N rows) ≈ 0.27 ms (fixed setup) + 5.0 µs × N

That is roughly ~145 µs per A4 page and ~42 allocations per row. Generation is single-threaded and the internal compression writers are pooled in a concurrency-safe way, so throughput scales ~linearly across cores when generating documents in parallel.

Documentation

• API reference
• Project docs
• HTML support
• Examples

Development

Contributor onboarding — toolchain setup, the multi-module workspace layout, golden-file tests, and mock generation — is covered in DEVELOPMENT.md.

Credits

Paper is derived from and inspired by Maroto, created by Johnathan Fercher da Rosa and contributors. The original project established the Bootstrap-style row and column PDF authoring model that Paper continues to evolve.

Logo art credit remains with @marinabankr.

License

Paper is released under the MIT License.