document

Documentation

Index

• type Attachment
• type Document
  • func New(filename string, opts ...Option) (*Document, error)
  • func NewWithFrontend(fe *frontend.Document, cssparser *csshtml.CSS) (*Document, error)
  • func (d *Document) AddCSS(css string) error
  • func (d *Document) AttachFile(a Attachment)
  • func (d *Document) Finish() error
  • func (d *Document) Headings() []HeadingEntry
  • func (d *Document) NewPage() error
  • func (d *Document) OutputAt(html string, width, x, y bag.ScaledPoint) error
  • func (d *Document) PageSize() (PageDimensions, error)
  • func (d *Document) ReadCSSFile(filename string) error
  • func (d *Document) RenderPages(html string) error
• type HeadingEntry
• type Option
  • func WithAttachment(a Attachment) Option
  • func WithPDFA3b() Option
  • func WithPDFUA() Option
  • func WithPDFX3() Option
  • func WithPDFX4() Option
  • func WithZUGFeRD(xmlData []byte, profile string) Option
• type PageDimensions

Types

type Attachment

type Attachment = document.Attachment

Attachment represents a file to embed in the PDF. Re-exported from the backend for convenience.

type Document

type Document struct {
	Title    string
	Author   string
	Keywords string // separated by comma
	Creator  string
	Subject  string
	Language string // BCP 47 language tag (e.g. "en", "de")
	Frontend *frontend.Document

	// PageInitCallback is called after each new page is initialized.
	// Use this for running headers/footers or page-level decorations.
	PageInitCallback func()

	// ElementCallback is called after each block element is rendered.
	// Use this for post-processing headings, paragraphs, etc.
	ElementCallback htmlbag.ElementCallbackFunc
	// contains filtered or unexported fields
}

Document is the main starting point of the PDF generation.

func New

func New(filename string, opts ...Option) (*Document, error)

New creates a PDF file at the given path. It initializes a boxes and glue frontend document and loads a default CSS stylesheet. Options can be passed to select a specific PDF format (e.g. WithPDFUA(), WithPDFA3b()).

func NewWithFrontend

func NewWithFrontend(fe *frontend.Document, cssparser *csshtml.CSS) (*Document, error)

NewWithFrontend creates a document from an existing boxes and glue frontend document and CSS parser. The default fonts (monospace, sans, serif) are loaded.

func (*Document) AddCSS

func (d *Document) AddCSS(css string) error

AddCSS reads CSS instructions from a string.

func (*Document) AttachFile

func (d *Document) AttachFile(a Attachment)

AttachFile embeds a file in the PDF document.

func (*Document) Finish

func (d *Document) Finish() error

Finish writes and closes the PDF file.

func (*Document) Headings

func (d *Document) Headings() []HeadingEntry

Headings returns all headings (h1–h6) found during rendering, with their page numbers. Only available after RenderPages has been called.

func (*Document) NewPage

func (d *Document) NewPage() error

NewPage starts a new page. Only needed in OutputAt mode for manual multi-page documents.

func (*Document) OutputAt

func (d *Document) OutputAt(html string, width, x, y bag.ScaledPoint) error

OutputAt renders an HTML fragment at an absolute position (x, y) on the current page with the given width. Use this for precise placement of content snippets (labels, letterheads, positioned boxes).

For full-page rendering with automatic page breaks, use RenderPages instead.

func (*Document) PageSize

func (d *Document) PageSize() (PageDimensions, error)

PageSize returns the dimensions of the current page (width, height, margins).

func (*Document) ReadCSSFile

func (d *Document) ReadCSSFile(filename string) error

ReadCSSFile parses the CSS file at the given path.

func (*Document) RenderPages

func (d *Document) RenderPages(html string) error

RenderPages renders a complete HTML document with automatic page breaks. Page size and margins are taken from CSS @page rules (default: A4 with 1cm margins). Content is distributed across pages automatically. Forced page breaks (page-break-before, page-break-after) are respected.

After calling RenderPages, call Finish to write the PDF. Do not mix RenderPages and OutputAt in the same document.

type HeadingEntry

type HeadingEntry = htmlbag.HeadingEntry

HeadingEntry re-exports the htmlbag type for convenience.

type Option

type Option func(*config)

Option configures document creation. Use the With* functions to create options.

func WithAttachment

func WithAttachment(a Attachment) Option

WithAttachment embeds a file in the PDF document. For PDF/A-3b documents the file appears as an associated file. Use this together with WithPDFA3b() for standards like ZUGFeRD/Factur-X, or use WithZUGFeRD for convenience.

func WithPDFA3b

func WithPDFA3b() Option

WithPDFA3b enables PDF/A-3b output.

func WithPDFUA

func WithPDFUA() Option

WithPDFUA enables PDF/UA (accessible PDF) output. All HTML elements are automatically tagged with their corresponding PDF structure roles (e.g. h1→H1, p→P, li→LI) so that screen readers and assistive technologies can interpret the content.

func WithPDFX3

func WithPDFX3() Option

WithPDFX3 enables PDF/X-3 output.

func WithPDFX4

func WithPDFX4() Option

WithPDFX4 enables PDF/X-4 output.

func WithZUGFeRD

func WithZUGFeRD(xmlData []byte, profile string) Option

WithZUGFeRD creates a ZUGFeRD/Factur-X compliant PDF. It sets the format to PDF/A-3b, attaches the XML invoice data as "factur-x.xml", and adds the required XMP extension schema metadata.

The profile parameter specifies the Factur-X conformance level: "MINIMUM", "BASIC WL", "BASIC", "EN 16931" (or "EN16931"), "EXTENDED", "XRECHNUNG".

type PageDimensions

type PageDimensions = htmlbag.PageDimensions

PageDimensions re-exports the htmlbag type for convenience.