Documentation
¶
Overview ¶
Package pdf renders HTML documents to PDF using Chromium.
Package pdf renders HTML documents to PDF using Chromium.
Index ¶
- func CheckChromiumAvailable() error
- func KillRunningBrowsers()
- func SetDocumentInfo(data []byte, meta DocumentMetadata, ts time.Time) ([]byte, error)
- func StripCoverHeaderFooter(data []byte) ([]byte, error)
- func WarnIfCJKFontsMissing(htmlContent string, logger interface{ ... })
- type DocumentMetadata
- type Generator
- type GeneratorOption
- func WithCoverPage(cover bool) GeneratorOption
- func WithDocumentOutline(enable bool) GeneratorOption
- func WithFooterTemplate(tmpl string) GeneratorOption
- func WithHeaderFooter(enable bool) GeneratorOption
- func WithHeaderTemplate(tmpl string) GeneratorOption
- func WithMarginStrings(left, right, top, bottom string) GeneratorOption
- func WithMargins(left, right, top, bottom float64) GeneratorOption
- func WithMetadata(m DocumentMetadata) GeneratorOption
- func WithPageSize(width, height float64) GeneratorOption
- func WithPrintBackground(print bool) GeneratorOption
- func WithTaggedPDF(enable bool) GeneratorOption
- func WithTimeout(d time.Duration) GeneratorOption
- type PDFRenderer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckChromiumAvailable ¶
func CheckChromiumAvailable() error
CheckChromiumAvailable reports whether Chrome or Chromium is installed.
func KillRunningBrowsers ¶ added in v0.8.2
func KillRunningBrowsers()
KillRunningBrowsers SIGKILLs every Chrome process this package started and has not yet reaped. Call it immediately before os.Exit on a path that skips deferred cleanup; it is a no-op when no render is in flight.
func SetDocumentInfo ¶ added in v0.8.0
SetDocumentInfo rewrites the /Info dictionary of an in-memory PDF so it carries mdPress's document metadata and a deterministic timestamp.
The rewrite is done in place whenever the new dictionary fits inside the bytes the old one occupied — that keeps every cross-reference offset valid and, because the replaced bytes included Chrome's wall-clock timestamps, makes the output reproducible. When the new dictionary is larger the old object is emptied and a replacement is appended as a standard incremental update.
Any PDF this function cannot confidently parse is returned unchanged along with an error, so a failure degrades to "metadata not set" rather than a corrupt file.
func StripCoverHeaderFooter ¶ added in v0.8.2
StripCoverHeaderFooter removes the print header and footer Chrome drew on page one of data, which is only correct when page one is a cover.
The document is returned unchanged, with an error explaining why, whenever the running head cannot be identified beyond doubt.
func WarnIfCJKFontsMissing ¶ added in v0.3.1
WarnIfCJKFontsMissing checks whether the HTML content contains CJK characters and warns the user if no CJK fonts are installed on the system. This is a best-effort check — it logs a warning but does not block PDF generation.
Types ¶
type DocumentMetadata ¶ added in v0.8.0
type DocumentMetadata struct {
Title string
Author string
Subject string
Keywords string
Creator string
}
DocumentMetadata is the document information mdPress records in a PDF's /Info dictionary. Empty fields are left out of the dictionary entirely.
func (DocumentMetadata) IsZero ¶ added in v0.8.0
func (m DocumentMetadata) IsZero() bool
IsZero reports whether no metadata field is set.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator converts HTML into PDF files.
func NewGenerator ¶
func NewGenerator(opts ...GeneratorOption) *Generator
NewGenerator creates a PDF generator. By default, it generates a document outline (clickable bookmarks) and tagged PDF.
type GeneratorOption ¶
type GeneratorOption func(*Generator)
GeneratorOption customizes a PDF generator.
func WithCoverPage ¶ added in v0.8.2
func WithCoverPage(cover bool) GeneratorOption
WithCoverPage declares that page one is a cover — artwork printed to the edge of the sheet — so the print header and footer are taken back off it after printing. Chrome draws them from the PrintToPDF parameters rather than from the page box, so nothing in the document can keep them off the cover; see StripCoverHeaderFooter.
func WithDocumentOutline ¶
func WithDocumentOutline(enable bool) GeneratorOption
WithDocumentOutline toggles PDF bookmark/outline generation from heading hierarchy. Enabled by default. Requires Chrome 128+ for full support.
func WithFooterTemplate ¶ added in v0.4.0
func WithFooterTemplate(tmpl string) GeneratorOption
WithFooterTemplate sets a custom HTML footer template for PDF pages. The template is rendered by Chrome's PrintToPDF and supports CSS styling. Chrome provides special classes: "pageNumber", "totalPages", "date", "title", "url".
func WithHeaderFooter ¶
func WithHeaderFooter(enable bool) GeneratorOption
WithHeaderFooter toggles header and footer rendering.
func WithHeaderTemplate ¶ added in v0.7.14
func WithHeaderTemplate(tmpl string) GeneratorOption
WithHeaderTemplate sets a custom HTML header template for PDF pages. The template is rendered by Chrome's PrintToPDF and supports CSS styling. Chrome provides special classes: "pageNumber", "totalPages", "date", "title", "url".
func WithMarginStrings ¶ added in v0.4.0
func WithMarginStrings(left, right, top, bottom string) GeneratorOption
WithMarginStrings sets page margins from string values (e.g., "20mm", "1in"). Uses default values if parsing fails.
func WithMargins ¶
func WithMargins(left, right, top, bottom float64) GeneratorOption
WithMargins sets page margins in millimeters.
func WithMetadata ¶ added in v0.8.0
func WithMetadata(m DocumentMetadata) GeneratorOption
WithMetadata sets the document information written into the PDF's /Info dictionary. Without it the PDF keeps whatever Chrome produced, which names headless Chrome as the creator and carries no author or subject.
func WithPageSize ¶
func WithPageSize(width, height float64) GeneratorOption
WithPageSize sets the page size in millimeters.
func WithPrintBackground ¶
func WithPrintBackground(print bool) GeneratorOption
WithPrintBackground toggles background printing.
func WithTaggedPDF ¶
func WithTaggedPDF(enable bool) GeneratorOption
WithTaggedPDF toggles tagged (accessible) PDF generation. Enabled by default. Tagged PDFs include structural metadata for screen readers.
func WithTimeout ¶
func WithTimeout(d time.Duration) GeneratorOption
WithTimeout sets the operation timeout.
type PDFRenderer ¶
type PDFRenderer interface {
Generate(ctx context.Context, htmlContent string, outputPath string) error
GenerateFromFile(ctx context.Context, htmlFilePath string, outputPath string) error
}
PDFRenderer abstracts PDF generation so tests can use a mock.
Both methods take a context because rendering a book-sized document keeps Chrome busy for minutes. Without one, Ctrl+C could not reach the render in progress: the CLI's signal handler canceled a context nothing in here was watching, so an interrupted build sat on a frozen progress line until Chrome had finished the whole book anyway.
Source Files