htmlbag
Library reference

Library reference

This section documents htmlbag’s Go API for code that imports github.com/boxesandglue/htmlbag directly. If you only consume htmlbag through bagme or glu, the content pages are what you need; this section is for embedders.

API stability: htmlbag has gone through several substantial refactors (Insert system, two-pass page assembly, CSS-property-based float detection) and more changes are expected before it stabilizes. Treat the API as moving until htmlbag (or its parent module) hits a tagged 1.0 release. The conceptual shape — CSSBuilder, OutputPages, the configuration fields — is unlikely to change dramatically, but field names and method signatures may.

Quick start

The minimal program: parse an HTML chunk, output it to a PDF.

package main

import (
    "log"

    "github.com/boxesandglue/boxesandglue/frontend"
    "github.com/boxesandglue/htmlbag"
)

func main() {
    fd, err := frontend.New("out.pdf")
    if err != nil { log.Fatal(err) }
    defer fd.Doc.Finish()

    // New loads the built-in font families (sans, serif, monospace).
    // NewCSSParserWithDefaults adds the user-agent stylesheet, so h1, p
    // and friends get their usual block behavior; NewCSSParser starts
    // from nothing and leaves all of that to you.
    cb, err := htmlbag.New(fd, htmlbag.NewCSSParserWithDefaults())
    if err != nil { log.Fatal(err) }

    if err := cb.AddCSS(`
        @page { size: A5; margin: 2cm }
        body { font-family: serif; font-size: 11pt; line-height: 1.4 }
    `); err != nil { log.Fatal(err) }

    te, err := cb.HTMLToText(`<html><body>
        <h1>Hello</h1>
        <p>World.</p>
    </body></html>`)
    if err != nil { log.Fatal(err) }

    if err := cb.OutputPagesFromText(te); err != nil { log.Fatal(err) }
}

For the canonical CSSBuilder construction inside speedata’s tools, look at how glu/lua/htmlbag/ and bagme/ set things up — they handle font loading, default styles, and structure tagging.

Core types

Type Role
CSS the stylesheet side: collects CSS from strings and files, matches the selectors against the DOM, and resolves the computed properties. Built with NewCSSParserWithDefaults (or NewCSSParser) and handed to New. Lived in the separate csshtml package until htmlbag v0.0.54
CSSBuilder central state — holds the CSS context, the in-flight page buffer, configuration knobs, and the current document accumulators (counters, headings, structure tree)
HTMLItem one node in the parsed and CSS-resolved DOM, with Styles and Attributes maps
Insert one extracted page-layer item (footnote or float) ready for placement
InsertClass distinguishes InsertFootnote, InsertFloatTop, InsertFloatBottom
HeadingEntry record of one heading found during VList construction; Page filled at output time

Core methods

Method When to use
NewCSSParserWithDefaults() *CSS build the CSS side with the user-agent stylesheet
NewCSSParser() *CSS same, but with no user-agent stylesheet
New(*frontend.Document, *CSS) (*CSSBuilder, error) construct; also loads the built-in fonts
AddCSS(string) error add CSS rules, resolving relative URLs against the working directory
ReadCSSFile(string) error add CSS from a file, resolving relative URLs against that file’s directory
HTMLToText(string) (*frontend.Text, error) parse + style HTML, return the styled tree
ParseHTMLFromNode(*html.Node) (*frontend.Text, error) same, from a pre-parsed DOM
CreateVlist(*frontend.Text, ScaledPoint) (*node.VList, error) format a styled tree into a VList without paginating
OutputPages(*node.VList) error paginate a pre-built VList
OutputPagesFromText(*frontend.Text) error paginate a styled tree, splitting at forced page breaks
NewPage() error force a page break (mid-output)

Subsections

  • Configuration — footnote and float layout fields, counters, page dimensions.
  • Callbacks — ElementCallback, PageInitCallback.
  • PDF/UA tagging — accessibility output via structure elements.