mathjax

README

mathjax-go

mathjax-go is a native Go port of the MathJax 3.2.2 TeX-to-SVG pipeline used by D2. Its production packages do not embed, load, or execute JavaScript.

The compatibility target is D2's frozen custom component, not current MathJax. That component enables the base, mathtools, ams, amscd, braket, cancel, cases, color, gensymb, mhchem, and physics TeX packages and uses SVG output with fontCache: 'none'.

svg, err := mathjax.Render(`\frac{1}{2}`)
width, height, err := mathjax.Measure(`\frac{1}{2}`)

Render uses the same conversion settings as D2: display mode, a 16-pixel em, an 8-pixel ex, and inline SVG glyph paths. RenderWithOptions exposes those settings explicitly. Both functions return the bare <svg> element that D2 previously obtained from the inner HTML of MathJax's <mjx-container>. Measure preserves D2's pixel sizing contract by rounding the SVG's ex-based dimensions up with the configured default of 8 pixels per ex.

As in MathJax, malformed or unsupported TeX is normally rendered as an merror SVG. A Go error instead indicates invalid conversion options or an internal pipeline failure.

Compatibility tests

The regular suite is pure Go:

go test ./...
go test -race ./...
go vet ./...

An optional test-only differential runner compares the port with D2's cryptographically pinned MathJax bundle. Node.js and the JavaScript assets are used only by this oracle and are not linked into the Go library:

MATHJAX_GO_ORACLE_DIR=/absolute/path/to/d2renderers/d2latex \
MATHJAX_GO_ORACLE_FULL=1 \
go test ./...

The directory must contain mathjax.js, polyfills.js, and setup.js with the exact SHA-256 values recorded in PROVENANCE.md.

License

Apache License 2.0, with identified MIT-derived portions. See LICENSE, LICENSES, NOTICE, and PROVENANCE.md.

Documentation

Overview

Package mathjax converts TeX math to SVG without a JavaScript runtime.

Its compatibility target is the custom MathJax 3.2.2 component embedded by D2. Render uses that component's display-mode, 16-pixel em, 8-pixel ex, and uncached-font-path defaults.

Index

• Constants
• func Measure(tex string) (width, height int, err error)
• func Render(tex string) (string, error)
• func RenderWithOptions(tex string, options Options) (string, error)
• type FontCacheMode
• type Options
  • func DefaultOptions() Options

Constants

const CompatibilityVersion = "3.2.2"

CompatibilityVersion is the upstream MathJax version whose behavior this module preserves.

Functions

func Measure

func Measure(tex string) (width, height int, err error)

Measure renders TeX with DefaultOptions and returns its rounded-up width and height in pixels. It preserves D2's MathJax 3.2.2 measurement contract: the serialized SVG dimensions are expressed in ex units and one ex is 8 pixels.

func Render

func Render(tex string) (string, error)

Render converts TeX to a bare SVG element using DefaultOptions. TeX syntax errors are represented by MathJax-compatible merror SVG; non-nil errors report an invalid option or an internal conversion failure.

func RenderWithOptions

func RenderWithOptions(tex string, options Options) (string, error)

RenderWithOptions converts TeX to a bare SVG element. The returned string is the equivalent of the inner HTML of MathJax's mjx-container. TeX syntax errors are represented by MathJax-compatible merror SVG.

Types

type FontCacheMode

type FontCacheMode uint8

FontCacheMode controls how glyph paths are represented in rendered SVG. MathJax-go initially supports FontCacheNone, which is the mode used by D2's frozen MathJax 3.2.2 component.

const (
	// FontCacheNone emits an independent SVG path for each glyph occurrence.
	FontCacheNone FontCacheMode = iota
)

type Options

type Options struct {
	// Em is the em size in pixels used to resolve relative lengths.
	Em float64
	// Ex is the ex size in pixels used to resolve relative lengths and report
	// the serialized SVG dimensions.
	Ex float64
	// Display selects display math when true and inline math when false.
	Display bool
	// FontCache controls SVG glyph reuse. Only FontCacheNone is supported.
	FontCache FontCacheMode
}

Options controls TeX-to-SVG conversion.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the options used by D2's frozen MathJax 3.2.2 integration.