Documentation
¶
Index ¶
- func CheckChromeAvailable() error
- func NewBrowser(ctx context.Context, opts Options) (context.Context, context.CancelFunc)
- func RenderToPDF(htmlContent string, outputPath string, opts Options) error
- type AuditReport
- func RenderToPDFWithAudit(htmlContent string, outputPath string, opts Options) (*AuditReport, error)
- func RenderToPDFWithAuditBrowser(browserCtx context.Context, htmlContent string, outputPath string, ...) (*AuditReport, error)
- func RenderToPDFWithAuditContext(ctx context.Context, htmlContent string, outputPath string, opts Options) (*AuditReport, error)
- type Issue
- type Options
- type Severity
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckChromeAvailable ¶
func CheckChromeAvailable() error
func NewBrowser ¶ added in v0.11.0
NewBrowser boots a headless Chrome allocator for rendering, tuned for minimal startup latency. The returned cancel tears down the browser; it must be deferred by the caller. The launch flags suppress the first-run experience, background networking, component updates, sync, and extensions — all of which Chrome would otherwise spin up on boot even though a PDF render uses none of them. These shave ~60-120ms off each cold start, and callers rendering many documents should create one browser and pass it to RenderToPDFWithAuditBrowser (or WithSharedBrowser on a PDF) to avoid the ~400ms startup cost entirely.
Types ¶
type AuditReport ¶ added in v0.8.0
type AuditReport struct {
Issues []Issue
}
AuditReport collects every Issue found while rendering a single document. A nil report or one with no Issues means the audit found nothing to flag — it does not guarantee the PDF is perfect, only that none of the checks it runs caught a problem.
func RenderToPDFWithAudit ¶ added in v0.8.0
func RenderToPDFWithAudit(htmlContent string, outputPath string, opts Options) (*AuditReport, error)
RenderToPDFWithAudit does exactly what RenderToPDF does, and additionally runs a best-effort visual/structural audit (see audit.go) of the composed document, returning its findings alongside any render error. The audit never turns a successful render into a failure: an audit finding is a warning about the *output*, not a reason to reject it.
Keeps this signature exactly as-is for API stability — it roots the browser in context.Background() internally, so a caller that needs to cancel an in-flight render (e.g. on client disconnect or SIGINT) should use RenderToPDFWithAuditContext instead.
func RenderToPDFWithAuditBrowser ¶ added in v0.11.0
func RenderToPDFWithAuditBrowser(browserCtx context.Context, htmlContent string, outputPath string, opts Options) (*AuditReport, error)
RenderToPDFWithAuditBrowser renders htmlContent to outputPath reusing an existing Chrome browser context instead of booting a new Chrome process. The browser must have been created with NewBrowser (or chromedp.NewContext over a shared allocator). This is how callers rendering many documents (e.g. docsgen's per-theme PDFs) avoid paying the ~400ms Chrome startup cost once per document: boot once, render N times.
The caller owns the browser lifetime: it must stay alive for the whole call and be closed (allocCancel) after all renders finish. opts.Timeout still bounds this single render. ctx cancels the in-flight render.
func RenderToPDFWithAuditContext ¶ added in v0.8.0
func RenderToPDFWithAuditContext(ctx context.Context, htmlContent string, outputPath string, opts Options) (*AuditReport, error)
RenderToPDFWithAuditContext is RenderToPDFWithAudit with the browser rooted in ctx instead of context.Background(): canceling ctx (client disconnect, SIGINT wired to context cancellation, etc.) now actually tears down the in-flight Chrome allocator/render instead of running to completion or to opts.Timeout regardless. opts.Timeout still applies as an upper bound layered on top of ctx via context.WithTimeout.
func (*AuditReport) HasIssues ¶ added in v0.8.0
func (r *AuditReport) HasIssues() bool
HasIssues reports whether the audit found anything worth surfacing to the caller. Safe to call on a nil report.
type Issue ¶ added in v0.8.0
type Issue struct {
// Check is a short, stable, machine-readable identifier for the rule
// that produced this issue (e.g. "overflow-x", "low-contrast",
// "heading-clip-risk"), suitable for filtering or documentation links.
Check string
Severity Severity
Message string
}
Issue is one finding from a post-compose/pre-print visual/structural audit of the document: something that renders but is likely wrong — clipped, overlapping, unreadable, or missing — rather than a hard error.
type Options ¶
type Options struct {
Timeout time.Duration
HeaderTitle string
MarginTop float64
MarginBottom float64
MarginLeft float64
MarginRight float64
PaperWidth float64
PaperHeight float64
NetworkAccess bool
PageNumbers bool
ShowHeader bool
// CoverImagePath, when non-empty, prepends a full-bleed cover page
// built from this image (.png/.jpg/.jpeg) before the rest of the
// document. That cover page's dimensions match the image's own pixel
// dimensions exactly (see coverImageDimensionsIn) rather than
// PaperWidth/PaperHeight — a square image gets a square cover page —
// while every other page keeps the configured paper size untouched.
CoverImagePath string
// ChromeExecPath, when non-empty, pins chromedp to this specific
// Chrome/Chromium/chrome-headless-shell binary instead of letting it
// search the system's default install locations. Callers resolving a
// browser via chromemgr.EnsureChrome pass its result straight through
// here; leaving it empty preserves the previous default-discovery
// behavior exactly.
ChromeExecPath string
// GenerateDocumentOutline, when true, asks Chrome to build the PDF
// bookmarks/outline tree from the document's headings. This is
// post-print work over the entire PDF and can be a significant chunk
// of render time on very large documents. Defaults to true (bookmarks
// are a headline feature); set false to trade them for speed.
GenerateDocumentOutline bool
// GenerateTaggedPDF, when true, asks Chrome to tag the PDF with
// accessibility structure (PDF/UA). This is post-print work over the
// entire PDF — the most expensive of the post-print steps on huge
// documents. Defaults to true (accessibility is valuable); set false
// for a meaningful speedup on very large documents.
GenerateTaggedPDF bool
}
func DefaultOptions ¶
func DefaultOptions() Options
type Severity ¶ added in v0.8.0
type Severity string
Severity classifies an audit Issue. The audit is advisory by default — every finding is a warning, never a hard failure — but a handful of checks (a corrupt or empty output, for instance) report at SeverityError so callers can decide to fail the build on them.
Source Files