Documentation
¶
Overview ¶
Package pdf defines renderer-neutral contracts for exporting Margo HTML to PDF.
Hosts provide an Engine, a Request containing materialized HTML and its runtime descriptor, and an explicit PageConfig and RelativeLinkPolicy. An engine returns PDF bytes together with runtime and engine provenance:
result, err := engine.Export(ctx, pdf.Request{
HTML: html,
Runtime: descriptor,
ExecutionID: executionID,
Page: page,
RelativeLinks: pdf.RelativeLinksStrip,
})
A typical Margo pipeline obtains html from RenderStandalone, obtains the descriptor from rendered.RuntimeDescriptor("ri-00000001"), and chooses a non-empty execution ID such as margo.ExecutionID("pdf-guide-1"). Construct pdf/chromium with an explicit installed browser path; neither package downloads or discovers a browser for the host.
Engines never select or fall back to another engine. Package pdf also does not discover or download a browser. Use package pdf/engines for deterministic discovery, or construct package pdf/chromium with an explicitly selected Chromium-family executable.
The zero relative-link policy strips document-relative links so a renderer's temporary origin cannot leak into a distributed PDF. PageConfig supports A4 and Letter pages, portrait and landscape orientation, non-negative margins in millimeters, and an optional image-height limit.
Reported browser versions are runtime evidence, not a compatibility minimum. Platform-native backends remain behind the pdf/native capability boundary and may be compiled out or unavailable.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CustomPageSize ¶ added in v0.0.7
type CustomPageSize struct {
WidthMM Millimeters `json:"widthMm"`
HeightMM Millimeters `json:"heightMm"`
}
CustomPageSize is an absolute physical PDF page size in millimetres.
type Engine ¶
type Engine interface {
Name() string
Version(context.Context) (string, error)
Export(context.Context, Request) (Result, error)
}
Engine exports one immutable HTML/runtime request through one explicitly selected renderer. Implementations never select or fall back to another engine.
type EngineInfo ¶
type EngineInfo struct {
Name string `json:"name"`
Version string `json:"version"`
Path string `json:"path,omitempty"`
Source string `json:"source,omitempty"`
}
EngineInfo records the selected engine identity without exposing an engine implementation value.
func (EngineInfo) Validate ¶
func (info EngineInfo) Validate() error
Validate rejects incomplete engine provenance.
type ExportReport ¶
type ExportReport struct {
PDF []byte `json:"pdf"`
DocumentFingerprint margo.DocumentFingerprint `json:"documentFingerprint"`
ArtifactFingerprint margo.ArtifactFingerprint `json:"artifactFingerprint"`
ArtifactDigest margo.ArtifactDigest `json:"artifactDigest"`
Engine EngineInfo `json:"engine"`
Runtime margo.RuntimeReport `json:"runtime"`
Page PageConfig `json:"page"`
CompilerVersion string `json:"compilerVersion"`
Theme margo.ThemeName `json:"theme"`
Assets map[string]string `json:"assets"`
Warnings []string `json:"warnings"`
}
ExportReport carries PDF bytes and renderer-neutral provenance. Native PDF byte digests are exact transport evidence but are not promised stable across engines or hosts.
func (ExportReport) Clone ¶
func (report ExportReport) Clone() ExportReport
Clone returns a report whose mutable values do not alias the receiver.
func (ExportReport) Validate ¶
func (report ExportReport) Validate() error
Validate checks the complete public provenance shape without selecting or invoking an engine.
type ImageOverflowPolicy ¶ added in v0.0.6
type ImageOverflowPolicy string
ImageOverflowPolicy controls whether print images are capped to keep one image from spanning several pages. The zero value uses ImageOverflowLimit.
const ( ImageOverflowLimit ImageOverflowPolicy = "limit" ImageOverflowAllow ImageOverflowPolicy = "allow" // DefaultImageMaxHeightPercent is the default maximum image height during // print projection, expressed as a percentage of the page viewport. DefaultImageMaxHeightPercent = 70 )
type Margins ¶
type Margins struct {
Top Millimeters `json:"top"`
Right Millimeters `json:"right"`
Bottom Millimeters `json:"bottom"`
Left Millimeters `json:"left"`
}
Margins defines the four non-negative physical page margins.
type Millimeters ¶
type Millimeters float64
Millimeters is a physical page length. Page margins use millimeters so all engines receive the same renderer-neutral values.
type Orientation ¶
type Orientation string
Orientation identifies the physical orientation of a page. An omitted orientation uses portrait mode.
const ( Portrait Orientation = "portrait" Landscape Orientation = "landscape" )
type PageConfig ¶
type PageConfig struct {
Size PageSize `json:"size"`
Orientation Orientation `json:"orientation"`
Custom *CustomPageSize `json:"custom,omitempty"`
Margins Margins `json:"margins"`
ImageOverflow ImageOverflowPolicy `json:"imageOverflow,omitempty"`
}
PageConfig is the engine-neutral physical page contract. Headers, footers, watermarks, and page numbers remain part of the supplied core HTML/CSS.
func (PageConfig) Clone ¶ added in v0.0.7
func (config PageConfig) Clone() PageConfig
func (PageConfig) EffectiveImageOverflowPolicy ¶ added in v0.0.6
func (config PageConfig) EffectiveImageOverflowPolicy() ImageOverflowPolicy
EffectiveImageOverflowPolicy returns the safe default for an omitted policy.
func (PageConfig) Validate ¶
func (config PageConfig) Validate() error
Validate rejects values that cannot be represented consistently by every engine covered by the v1 contract.
type PageSize ¶
type PageSize string
PageSize identifies one physical page size supported by the v1 contract.
type RelativeLinkPolicy ¶ added in v0.0.4
type RelativeLinkPolicy string
RelativeLinkPolicy controls how document-relative anchors are projected into a PDF. The zero value is the safe strip policy because a renderer's temporary document origin must never leak into a distributed artifact by default.
const ( RelativeLinksStrip RelativeLinkPolicy = "strip" RelativeLinksError RelativeLinkPolicy = "error" RelativeLinksKeep RelativeLinkPolicy = "keep" RelativeLinksResolve RelativeLinkPolicy = "resolve" )
type Request ¶
type Request struct {
HTML []byte `json:"html"`
Runtime margo.RuntimeDescriptor `json:"runtime"`
ExecutionID margo.ExecutionID `json:"executionID"`
Page PageConfig `json:"page"`
RelativeLinks RelativeLinkPolicy `json:"relativeLinks,omitempty"`
BaseURL string `json:"baseURL,omitempty"`
}
Request is the renderer-neutral input shared by every PDF engine.
type Result ¶
type Result struct {
PDF []byte `json:"pdf"`
Runtime margo.RuntimeReport `json:"runtime"`
Engine EngineInfo `json:"engine"`
}
Result is the renderer-neutral output returned by an Engine.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package chromium exports immutable Margo HTML through an explicitly selected installed Chromium-family executable.
|
Package chromium exports immutable Margo HTML through an explicitly selected installed Chromium-family executable. |
|
Package native defines the stable capability boundary for platform-native PDF engines.
|
Package native defines the stable capability boundary for platform-native PDF engines. |
|
Package platform verifies the locked platform probe contract without selecting, downloading, or implementing a PDF engine.
|
Package platform verifies the locked platform probe contract without selecting, downloading, or implementing a PDF engine. |