PDF API

Piko renders PDF output from PK templates using a fluent builder. The render pipeline supports metadata, watermarks, PDF/A conformance, accessibility tagging via TaggedPDF(), and custom page labels. It also supports additional CSS stylesheets and font-size and line-height overrides. The pipeline also supports native SVG-to-PDF vector rendering and post-processing transformers for encryption and signing. For the design rationale see about PDF. For task recipes see how to PDF generation. Source of truth: wdk/pdf/facade.go.

Service

Builder

The fluent RenderBuilder composes a single render operation. Chain setters, then call Do(ctx) to execute.

Watermark(text) is the convenience form using default styling (60pt, light grey, 45 degrees). Use WatermarkConfig for full control. PdfA(PdfA2A) enables tagged-PDF accessibility output automatically. The builder has no Fonts setter - the service configures fonts at construction time, not per render.

Types

Constants

Post-processing transformers

Transformers run after the initial render pass. Register them through a TransformerRegistry, then attach the registry to the builder via Transformations(registry, config). Each transformer has a paired option struct that tunes its behaviour.

Option structs

Transformer options live in pdfwriter_dto, and the wdk/pdf facade aliases them. The fields below match the source structs exactly.

EncryptionOptions

PadesSignOptions

WatermarkOptions

PdfAOptions

The string Level is the transformer-side configuration. The builder's PdfA(level PdfALevel) setter takes the typed PdfALevel constants (PdfA2B, PdfA2U, PdfA2A) instead.

PdfUAOptions

Empty struct. The PDF/UA transformer takes no configuration. Passing it enables PDF/UA enhancement.

LineariseOptions

Empty struct. The linearisation transformer takes no configuration.

ObjStmOptions

Empty struct. The object-stream compression transformer takes no configuration.

FlattenOptions

RedactionOptions

CompressOptions

RedactionRegion

Registry

func NewTransformerRegistry() *TransformerRegistry

*TransformerRegistry is an alias for *pdfwriter_domain.PdfTransformerRegistry. It exposes four methods:

Transformer interface

TransformerPort is the interface implementations satisfy:

type TransformerPort interface {
    Name() string
    Type() pdfwriter_dto.TransformerType
    Priority() int
    Transform(ctx context.Context, pdf []byte, options any) ([]byte, error)
}

TransformConfig is the bundle passed to the builder through Transformations(registry, config). It has two fields:

pdfwriter_dto.DefaultTransformConfig() returns a TransformConfig with no transformers enabled and an empty options map.

Rendering SVG inside a PDF

SVGWriterPort renders SVG content as native PDF vector commands. SVGDataPort provides raw SVG markup. Users who need custom SVG-to-PDF conversion implement one of these ports and plug it into the painter configuration.

Bootstrap

PDF does not expose a dedicated With* option. Piko constructs the default service from the PDF manifest produced by the project's scaffolded generator (cmd/generator/main.go) when a pdfs/ directory is present in the project. Custom transformers register through the TransformerRegistry:

registry := pdf.NewTransformerRegistry()
if err := registry.Register(pdf.NewEncryptTransformer()); err != nil {
    return err
}
if err := registry.Register(pdf.NewPadesSignTransformer()); err != nil {
    return err
}

Attach the registry and selection config to the builder via Transformations(registry, config). The config is a TransformConfig describing which transformers to enable and their options.

See also

• About PDF for why PDFs sit on the same template substrate and when to reach for PDF/A or digital signatures.
• How to PDF generation for rendering a PK template, adding metadata, watermarks, and encryption.
• Scenario 027: PDF invoice for a runnable example.