html

Documentation

Overview

Package html converts HTML+CSS markup into layout elements that the github.com/carlos7ags/folio/layout package can render to PDF.

The converter parses an HTML string (via golang.org/x/net/html), resolves inline and <style> CSS, and produces a tree of layout.Element values — Paragraphs, Divs, Tables, Lists, Images, and so on — ready to be fed to the layout engine.

Supported HTML elements include headings (<h1>–<h6>), paragraphs, spans, divs, tables, lists, images, SVG, links, and line breaks. CSS features include selectors, the box model, flexbox, grid, floats, absolute positioning, @page rules with margin boxes, CSS counters, and web fonts via @font-face.

Index

• func Convert(htmlStr string, opts *Options) ([]layout.Element, error)
• type AbsoluteItem
• type ConvertResult
  • func ConvertFull(htmlStr string, opts *Options) (*ConvertResult, error)
• type DocMetadata
• type MarginBoxContent
• type Options
• type PageConfig
• type PageMargins

Functions

func Convert

func Convert(htmlStr string, opts *Options) ([]layout.Element, error)

Convert parses an HTML string and returns a slice of layout elements suitable for passing to a layout.Renderer. Only a subset of HTML is supported — see package documentation for details.

Types

type AbsoluteItem

type AbsoluteItem struct {
	Element      layout.Element
	X, Y         float64 // X from left edge, Y from top in PDF coordinates (bottom-left origin)
	Width        float64
	Fixed        bool // position:fixed (render on every page)
	RightAligned bool // true when positioned with CSS right (X is right-edge offset)
	ZIndex       int  // z-index: negative = render behind normal flow
}

AbsoluteItem represents an element removed from normal flow via position:absolute or position:fixed.

type ConvertResult

type ConvertResult struct {
	Elements   []layout.Element
	Absolutes  []AbsoluteItem
	PageConfig *PageConfig // page settings from @page rules (nil if none)
	Metadata   DocMetadata // extracted from <title> and <meta> tags
}

ConvertResult holds the full result of an HTML → layout conversion, including both normal-flow elements and absolutely positioned items.

func ConvertFull

func ConvertFull(htmlStr string, opts *Options) (*ConvertResult, error)

ConvertFull parses an HTML string and returns both normal-flow elements and absolutely positioned items.

type DocMetadata

type DocMetadata struct {
	Title       string // from <title>
	Author      string // from <meta name="author">
	Description string // from <meta name="description">
	Keywords    string // from <meta name="keywords">
	Creator     string // from <meta name="generator">
	Subject     string // from <meta name="subject">
}

DocMetadata holds document metadata extracted from HTML head elements.

type MarginBoxContent

type MarginBoxContent struct {
	Content  string     // resolved content string (after evaluating counter(), string literals, etc.)
	FontSize float64    // font size in points (0 = use default 9pt)
	Color    [3]float64 // RGB color (0-1 each; all zero = default gray)
}

MarginBoxContent holds the parsed content of a CSS margin box (e.g. @top-center).

type Options

type Options struct {
	// DefaultFontSize is the root font size in points (default 12).
	DefaultFontSize float64
	// BasePath is the base directory for resolving relative image/font/CSS paths.
	BasePath string
	// PageWidth is the page width in points (default 612 = US Letter).
	PageWidth float64
	// PageHeight is the page height in points (default 792 = US Letter).
	PageHeight float64
	// FallbackFontPath is the path to a Unicode-capable TTF/OTF font used
	// when text contains characters outside WinAnsiEncoding (e.g. CJK, emoji).
	// If empty, the converter searches common system font locations.
	FallbackFontPath string
}

Options configures the HTML → layout.Element conversion.

type PageConfig

type PageConfig struct {
	Width      float64 // page width in points (0 = use default)
	Height     float64 // page height in points (0 = use default)
	AutoHeight bool    // true when @page size has explicit height of 0 (size to content)
	Landscape  bool

	// Default margins (from @page with no pseudo-selector).
	MarginTop    float64
	MarginRight  float64
	MarginBottom float64
	MarginLeft   float64
	HasMargins   bool // true if any margin property was explicitly set (even to 0)

	// Per-page-type margin overrides (nil = use default).
	First *PageMargins // @page :first
	Left  *PageMargins // @page :left (even pages in LTR)
	Right *PageMargins // @page :right (odd pages in LTR)

	// Default margin boxes (from @page with no pseudo-selector).
	MarginBoxes map[string]MarginBoxContent // e.g. "top-center" → content
}

PageConfig holds page dimensions and margins from CSS @page rules.

type PageMargins

type PageMargins struct {
	Top, Right, Bottom, Left float64
	HasMargins               bool                        // true if any margin property was explicitly set (even to 0)
	MarginBoxes              map[string]MarginBoxContent // e.g. "top-center" → content
}

PageMargins holds the margin values and margin-box content for a page variant (e.g. :first, :left, :right) parsed from a CSS @page rule.