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 stabilises. 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/backend/document"
    "github.com/boxesandglue/boxesandglue/frontend"
    "github.com/boxesandglue/csshtml"
    "github.com/boxesandglue/htmlbag"
)

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

    css := csshtml.NewCSSParser()
    cb, err := htmlbag.New(fd, css)
    if err != nil { log.Fatal(err) }

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

    if err := cb.AddCSSText(`
        @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
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
New(*frontend.Document, *csshtml.CSS) (*CSSBuilder, error) construct
AddCSSText(string) error add CSS rules
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.