API Reference

Full reference on pkg.go.dev.

Render functions

func Display(w io.Writer, equation string, opts Options) error
func Inline(w io.Writer, equation string, opts Options) error
func Render(w io.Writer, equation string, opts Options) error

All three compile the equation, produce a PNG, and write terminal graphics to w.

Options

type Options struct {
    Backend    Backend     // Auto (default), PDFLaTeX, Tectonic, DVIPng
    Protocol   Protocol    // AutoProtocol, Kitty, Sixel, HalfBlock
    DPI        int         // PNG render resolution; default 150
    MaxWidth   int         // pixel cap before scaling to terminal; 0 = fit
    MaxHeight  int         // pixel cap; 0 = fit
    Packages   []string    // extra \usepackage entries in the preamble
    Foreground color.Color // glyph color; nil = auto-detect from terminal
    Background color.Color // background color; nil = auto-detect from terminal
    NoTheme    bool        // skip recoloring; display raw black-on-white
}

Theme matching

The TeX backend renders black glyphs on white. Before display the PNG is recolored to match the terminal so it never shows a white box on a dark background.

type Theme struct {
    Fg color.Color // glyph color
    Bg color.Color // background color
}

func DetectTheme() Theme

DetectTheme queries the controlling terminal over /dev/tty for its foreground (OSC 10) and background (OSC 11) colors, parsing the rgb:RRRR/GGGG/BBBB reply. If the terminal does not answer it falls back to $COLORFGBG, then to light-on-dark.

Glyph pixels are mapped to Fg, paper pixels to Bg, antialiased edges blended between — the output is fully opaque, so it works in every protocol.

• Options.Foreground / Options.Background override either color. A nil field is auto-detected.
• Options.NoTheme = true disables recoloring entirely.

// Force cyan glyphs on a near-black background.
termlatex.Display(os.Stdout, `x^2`, termlatex.Options{
    Foreground: color.NRGBA{R: 0, G: 200, B: 255, A: 255},
    Background: color.NRGBA{R: 20, G: 20, B: 20, A: 255},
})

Backend

type Backend int
const (
    Auto      Backend = iota // try PDFLaTeX → Tectonic → DVIPng
    PDFLaTeX                 // pdflatex + pdftoppm
    Tectonic                 // tectonic + pdftoppm
    DVIPng                   // latex + dvipng
)

func Detect() (Backend, error)
func (b Backend) String() string

Protocol

Protocol detection and encoding are built in — no external display dependency.

type Protocol int

const (
    AutoProtocol Protocol = iota // detect from $TERM / $TERM_PROGRAM
    HalfBlock                    // Unicode ▀, works everywhere
    Sixel                        // DEC Sixel
    Kitty                        // Kitty graphics protocol
)

func (p Protocol) String() string

AutoProtocol picks Kitty (kitty, Ghostty, WezTerm), Sixel (foot, mlterm, contour, *sixel* terminals), or HalfBlock otherwise.

Errors

var (
    ErrNoBackend    = errors.New("no LaTeX backend found in PATH")
    ErrRenderFailed = errors.New("LaTeX render failed")
    ErrDisplay      = errors.New("terminal display failed")
)

All are matchable with errors.Is. ErrRenderFailed wraps the tool's combined stdout/stderr (last 20 lines) so you can surface the TeX error message to the user.