builder

Documentation

Overview

Package builder provides a library API for deckle: fetch URLs and produce clean HTML, Markdown, or EPUB suitable for e-readers.

The primary entry point is Build, which accepts a list of URLs and an Options struct controlling output format, image optimization, and other settings.

err := builder.Build(urls, builder.Options{
    Format: "epub",
    Output: "book.epub",
})

Cover image generation for epub output. Supports multiple cover styles: "typographic" (default), "collage", and "pattern".

Epub generation from HTML articles using go-epub. Replaces pandoc for combining multiple articles into an epub3 with TOC.

Image optimization for HTML with base64-embedded images. Resizes, converts to grayscale, JPEG-encodes for e-readers.

Markdown export: converts processed articles to CommonMark Markdown.

Pipeline functions: URL processing, parallel fetching, and output assembly.

Verbose output for deckle. Default: no output except errors. With -v, simple summary lines on stderr.

HTML to XHTML sanitization for EPUB 3 compliance. Converts arbitrary HTML from the web into valid XHTML suitable for embedding in EPUB 3 documents.

Index

• func Build(urls []string, opts Options) error
• func RunCLI(inputFile string, args []string, stdinReader io.Reader, opts Options) error
• type Options

Functions

func Build

func Build(urls []string, opts Options) error

Build processes the given inputs and produces output in the specified format. Each input may be an HTTP(S) URL or a local file path (HTML or Markdown). Local paths start with /, ./, ../, ~/, or file://. For epub format, Options.Output must be set.

This is the main entry point for using deckle as a library.

func RunCLI

func RunCLI(inputFile string, args []string, stdinReader io.Reader, opts Options) error

RunCLI executes the CLI-oriented workflow: collects URLs from all sources (input file, args, stdin) and calls Build. This is used by the CLI wrapper and supports txt file title derivation for epub.

Types

type Options

type Options struct {
	// Title overrides the article or book title.
	Title string

	// Output is the file path to write to. Required for epub format.
	// For html and markdown, if empty the result is written to Writer
	// (which defaults to os.Stdout).
	Output string

	// Format is the output format: "html", "markdown", or "epub".
	// Defaults to "markdown" if empty.
	Format string

	// MaxWidth is the maximum image pixel width (height scales proportionally).
	// Defaults to 800.
	MaxWidth int

	// Quality is the JPEG quality (1-95) for optimized images.
	// Defaults to 60.
	Quality int

	// Grayscale converts images to grayscale when true.
	Grayscale bool

	// Timeout is the HTTP fetch timeout. Defaults to 30s.
	Timeout time.Duration

	// UserAgent is the HTTP User-Agent header. Defaults to a Firefox UA string.
	UserAgent string

	// CoverStyle controls epub cover generation: "typographic" (default),
	// "collage", "pattern", or "none".
	CoverStyle string

	// Concurrency is the maximum number of concurrent downloads for articles
	// and images. Defaults to 5.
	Concurrency int

	// MaxResponseSize is the maximum allowed HTTP response size in bytes.
	// 0 means unlimited. Defaults to 128 MB.
	MaxResponseSize int64

	// ProxyURL is an HTTP proxy URL for all outgoing requests.
	// When set, deckle falls back to standard TLS (no browser fingerprinting).
	ProxyURL string

	// Verbose enables progress output written to LogWriter.
	Verbose bool

	// LogWriter receives verbose/progress output when Verbose is true.
	// Defaults to os.Stderr.
	LogWriter io.Writer

	// Writer receives html/markdown output when Output is empty.
	// Defaults to os.Stdout. Ignored for epub format.
	Writer io.Writer
}

Options configures a Build invocation.