mathml

README

goldmark-mathml

goldmark-mathml is a Goldmark extension that parses GitHub-style mathematical expressions and renders them server-side as native MathML.

It emits no client-side JavaScript. The TeX-to-MathML conversion is performed by an embedded copy of Temml running in the pure-Go Goja JavaScript runtime.

Usage

package main

import (
    "os"

    mathml "github.com/filippo-agent/goldmark-mathml"
    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/extension"
)

func main() {
    markdown := goldmark.New(goldmark.WithExtensions(
        extension.GFM,
        mathml.New(),
    ))
    if err := markdown.Convert([]byte("Euler wrote $e^{i\\pi}+1=0$."), os.Stdout); err != nil {
        panic(err)
    }
}

The extension and its renderer are safe for concurrent use. Initialized rendering runtimes are pooled and reused.

By default, an invalid expression stops rendering and returns a typed *mathml.RenderError, which callers can identify with errors.As. This is useful in linters and build pipelines. Long-lived servers can instead keep the page available and emit a visible, safely escaped warning where the expression would have appeared:

mathml.New(mathml.WithErrorFallback(nil))

The fallback itself is always rendered as HTML: a warning containing the safely escaped original expression. The argument is an optional reporting callback; it does not produce rendered output. Pass nil unless the application has a specific use for out-of-band error reporting.

The checked-in testdata/github.json corpus contains GitHub /markdown API results for delimiter, escaping, currency, Markdown-nesting, and fenced-block edge cases. Tests compare the inline and display expressions recognized by this extension with those recognized by GitHub.

For consistent native MathML rendering across browsers, serve the bundled Temml stylesheet and supplemental font:

mux.Handle("GET /mathml/", http.StripPrefix("/mathml/",
    http.FileServerFS(mathml.Assets())))

and include it in the page:

<link rel="stylesheet" href="/mathml/temml.css">

The stylesheet is optional for basic MathML. It contains browser workarounds and improves accents, primes, and script glyphs; it does not contain JavaScript.

Syntax

The supported syntax follows GitHub's documented mathematical-expression format:

Inline math: $x^2 + y^2$

Inline math containing Markdown-significant characters: $`x_{*}`$

$$
x^2 + y^2 = z^2
$$

```math
x^2 + y^2 = z^2
```

A display expression may also place both $$ delimiters on one otherwise empty line:

$$x^2 + y^2 = z^2$$

To write a literal dollar inside an expression, use GitHub's backtick form and escape the dollar for TeX:

$`\sqrt{\$4}`$

To write a literal dollar outside math on a line that also contains an expression, use GitHub's documented HTML escape:

To split <span>$</span>100 in half, calculate $100/2$.

Ordinary code spans and code fences are never interpreted as math. A display block cannot interrupt an existing Markdown paragraph; separate it from prose with a blank line.

Errors

Invalid TeX causes Goldmark rendering to return an error. This makes malformed expressions visible in tests and build pipelines instead of silently emitting broken markup.

Third-party code

The embedded internal/temml/temml.min.js, assets/temml.css, and assets/Temml.woff2 are from Temml v0.13.4. Its license is in internal/temml/LICENSE.

Documentation

Overview

Package mathml provides a Goldmark extension that parses GitHub-style mathematical expressions and renders them server-side as native MathML.

Index

• Variables
• func Assets() fs.FS
• func New(options ...Option) goldmark.Extender
• type Block
  • func (n *Block) Dump(source []byte, level int)
  • func (*Block) IsRaw() bool
  • func (*Block) Kind() ast.NodeKind
• type ErrorReporter
• type Inline
  • func (n *Inline) Dump(source []byte, level int)
  • func (*Inline) Inline()
  • func (*Inline) IsBlank([]byte) bool
  • func (*Inline) Kind() ast.NodeKind
• type Option
  • func WithErrorFallback(reporter ErrorReporter) Option
• type RenderError
  • func (e *RenderError) Error() string
  • func (e *RenderError) Unwrap() error

Variables

var (
	KindInline = ast.NewNodeKind("MathInline")
	KindBlock  = ast.NewNodeKind("MathBlock")
)

Functions

func Assets

func Assets() fs.FS

Assets returns the Temml stylesheet and its small supplemental font as an fs.FS rooted at the assets directory. Web applications can serve it with http.FileServerFS. The stylesheet is optional for basic MathML rendering but works around browser differences and improves accents and script glyphs.

func New

func New(options ...Option) goldmark.Extender

New returns a Goldmark extension for GitHub-style mathematical expressions. It supports $...$ and $`...`$ inline math, $$...$$ display math, and fenced code blocks whose language is "math". Expressions are rendered to MathML on the server; no client-side JavaScript is emitted.

Types

type Block

type Block struct {
	ast.BaseBlock
	Equation []byte
	// contains filtered or unexported fields
}

Block is a display mathematical expression.

func (*Block) Dump

func (n *Block) Dump(source []byte, level int)

func (*Block) IsRaw

func (*Block) IsRaw() bool

func (*Block) Kind

func (*Block) Kind() ast.NodeKind

type ErrorReporter

type ErrorReporter func(expression string, display bool, err error)

type Inline

type Inline struct {
	ast.BaseInline
	Equation []byte
	Display  bool
}

Inline is an inline mathematical expression. Display is true for an expression delimited by double dollar signs in a paragraph.

func (*Inline) Dump

func (n *Inline) Dump(source []byte, level int)

func (*Inline) Inline

func (*Inline) Inline()

func (*Inline) IsBlank

func (*Inline) IsBlank([]byte) bool

func (*Inline) Kind

func (*Inline) Kind() ast.NodeKind

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option configures the extension.

func WithErrorFallback

func WithErrorFallback(reporter ErrorReporter) Option

WithErrorFallback makes rendering continue when Temml rejects an expression. Invalid inline expressions are emitted as visible warning spans and invalid display expressions as warning blocks, with the original expression safely escaped. If reporter is non-nil, it is called for each rejected expression as an out-of-band notification and does not affect the rendered output. Without this option, rendering stops and returns the error.

type RenderError

type RenderError struct {
	Expression string
	Display    bool
	Err        error
}

RenderError reports an expression that Temml could not render. It can be identified with errors.As.

func (*RenderError) Error

func (e *RenderError) Error() string

func (*RenderError) Unwrap

func (e *RenderError) Unwrap() error