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.
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 ¶
Constants ¶
This section is empty.
Variables ¶
var ( KindInline = ast.NewNodeKind("MathInline") KindBlock = ast.NewNodeKind("MathBlock") )
Functions ¶
func Assets ¶ added in v0.2.0
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.
Source Files