html

package
v0.1.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package html converts HTML documents (.html, .xhtml, and web pages saved as MHTML) into BDF documents in reader mode.

Like a browser's reader view, the converter keeps the content and leaves the page's design out: the article is picked out of the page (with go-readability, a port of Mozilla's Readability) and its elements take the formatting of a fixed style sheet, not the page's CSS. Headings, paragraphs, lists, quotations, code, tables, figures, links and images are laid out by the layout engine of the Word converter (converter/internal/wordproc), with the fonts embedded as subsets. BDF does not lay text out again, so the document converts into a scroll view of a fixed width (docs/spec.md §4.1); a view of A4 pages can be added.

Images are read from the files beside the document, from an MHTML archive, from data: URLs and, unless Options.NoRemote is set, from the network. See docs/design.md §3.16.

Index

Constants

View Source
const (
	ViewsScroll = wordproc.ViewsScroll
	ViewsPages  = wordproc.ViewsPages
	ViewsBoth   = wordproc.ViewsBoth
)

View selections.

View Source
const (
	// ExtractAuto picks the article out of pages that look like they have
	// one (Readability's isProbablyReaderable), and keeps the whole of
	// other documents.
	ExtractAuto = "auto"
	// ExtractArticle always picks the article out.
	ExtractArticle = "article"
	// ExtractNone keeps the whole document.
	ExtractNone = "none"
)

Article extraction.

Variables

View Source
var Params = []conv.Param{
	{Name: "views", Usage: "scroll (default): one long column; pages: A4 pages; both"},
	{Name: "width", Usage: "text width of the scroll view in points (default: 36 ems of the text)"},
	{Name: "size", Usage: "text size in points (default 12)"},
	{Name: "font", Usage: "font family of the text (default: an installed sans-serif family)"},
	{Name: "mono", Usage: "font family of code (default: an installed monospaced family)"},
	{Name: "remote", Usage: "true (default): fetch images from the network; false: leave them out"},
	{Name: "private", Usage: "true: fetch images from private and local addresses too (default false: public addresses only)"},
	{Name: "base", Usage: "URL the document came from: relative links and images resolve against it"},
}

Params are the format-specific options of HTML and Markdown documents.

Functions

func IsHTML

func IsHTML(data []byte) bool

IsHTML reports whether data starts like a whole HTML document: a doctype or an html element, after white space, comments and an XML declaration. Fragments (a README that starts with <p align="center">) are left to the Markdown converter, whose raw HTML they are.

func IsMHTML

func IsMHTML(data []byte) bool

IsMHTML reports whether data starts like a web archive (MHTML): MIME headers with a multipart/related content type.

func Summary

func Summary(res *Result) *conv.Result

Summary makes a registry result of a result.

Types

type Options

type Options struct {
	// Views selects the views to make: ViewsScroll (the default when ""),
	// ViewsPages (A4 pages) or ViewsBoth.
	Views string
	// Pages selects 1-based pages of the page view (see converter.Pages);
	// nil keeps every page.
	Pages conv.Pages
	// Title overrides the document title.
	Title string
	// Extract controls how the article is picked out of the page:
	// ExtractAuto (the default when ""), ExtractArticle or ExtractNone.
	Extract string

	// Dir is the directory relative references (images) resolve in;
	// references and symlinks must stay within it. ""
	// reads no local files. ConvertFile sets it to the file's directory.
	Dir string
	// BaseURL is the address of the document: relative references resolve
	// against it, and links become absolute. A <base> element or the
	// address an MHTML archive was saved from takes precedence.
	BaseURL string
	// NoRemote leaves out the images on the network instead of fetching
	// them. A server that converts documents it does not trust should set
	// it, or give a Fetch that limits what can be reached.
	NoRemote bool
	// Fetch loads an http: or https: URL; nil uses an HTTP client with a
	// timeout and a size limit. It is called for several images at the same
	// time.
	Fetch func(url string) ([]byte, error)
	// AllowPrivate lets the HTTP client fetch from addresses that are not
	// public on the Internet (the host itself, its network, its link),
	// which it refuses otherwise: a document a server converts could reach
	// what is private to the server through them. It does not apply to
	// Fetch, nor when the environment names a proxy.
	AllowPrivate bool

	// Width is the text width of the scroll view in points (0: 36 ems).
	Width float64
	// FontSize is the size of the text in points (0: 12).
	FontSize float64
	// Font and MonoFont are the font families of the text and of code
	// ("": installed ones are picked).
	Font, MonoFont string

	// Images controls whether raster images are re-encoded (see imgconv).
	// The zero value keeps images as they are.
	Images imgconv.Options
	// FontFS holds fonts that are not in the local file system; it is
	// searched before FontDirs (see converter.Options.FontFS).
	FontFS fs.FS
	// FontDirs are searched for fonts before the system font directories.
	FontDirs []string
	// NoSystemFonts restricts font lookup to FontFS and FontDirs.
	NoSystemFonts bool
	// EmbedFonts embeds the fonts the text is laid out with, as subsets.
	// By default the fonts are referred to by name (the text families as
	// the generic sans-serif and monospace), and viewers draw the text with
	// their own fonts, keeping the advances measured here.
	EmbedFonts bool
	// NoSubset embeds whole fonts instead of the glyphs in use.
	NoSubset bool
	// NoWOFF2 stores embedded fonts as TrueType/OpenType instead of WOFF2.
	NoWOFF2 bool
	// IgnoreFSType embeds fonts whose OS/2 fsType forbids embedding or
	// subsetting. Set it only when you hold the rights to embed the fonts.
	IgnoreFSType bool
	// NoTextIndex skips building the text index parts.
	NoTextIndex bool
	// Warn receives non-fatal problems; when nil they are collected in
	// Result.Warnings.
	Warn func(msg string)
}

Options controls the conversion.

func FromConverter

func FromConverter(o *conv.Options) (*Options, error)

FromConverter maps the registry's options (and Params) onto Options.

type Result

type Result struct {
	Doc           *bdf.Document
	Warnings      []string
	Pages         int  // pages of the page view
	Strips        int  // strips of the scroll view
	EmbeddedFonts int  //
	Extracted     bool // the article was picked out of the page
	Images        int  // images drawn
}

Result is the outcome of a conversion.

func Convert

func Convert(r io.ReaderAt, size int64, opts *Options) (*Result, error)

Convert converts a document read from r.

func ConvertBytes

func ConvertBytes(data []byte, opts *Options) (*Result, error)

ConvertBytes converts an HTML document or an MHTML archive.

func ConvertFile

func ConvertFile(path string, opts *Options) (*Result, error)

ConvertFile converts an HTML or MHTML file; relative references resolve in its directory (unless opts.Dir says otherwise).

func ConvertNode

func ConvertNode(doc *xhtml.Node, opts *Options) (*Result, error)

ConvertNode converts a parsed document.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL