Mathematics

Mathematical expressions are first-class ScriptPub content. They are not plain text styled to resemble mathematics and are not image fallbacks. A formula is an atomic object run, so it occupies one caret position, may sit inside prose, may carry the same mark stack as text, and may be the sole run of an equation block.

The math object

InlineMathObject = {
  type: "math",
  latex?: string,       // TeX/LaTeX source, without delimiters
  mathml?: string,      // sanitized native MathML rooted at <math>
  display?: boolean,    // false/absent = inline; true = display math
  alt?: string,         // optional accessible/plain-text alternative
  // shared ElementAttrs: class, style, role, epubType, aria, lang, dir, data
}

At least one of latex or mathml MUST be present. latex is the preferred editable authority when a source provides it. mathml is retained when native MathML is the source authority and converting it back to TeX would lose information. An importer MAY keep both. $, $$, \(, \), \[, and \] are syntax delimiters and are never stored in latex.

display belongs to the expression rather than a hard-coded block kind. A format MAY define an equation text block and style it separately; a display math object also works in the default Paragraph block. An equation number or nearby explanatory prose remains ordinary content. The math object itself remains atomic and never exposes its TeX commands as document prose.

The file spelling

In the .spub.html file a formula is a native <math> element — sanitized MathML, plus data-spub-latex carrying the TeX source when TeX is authoritative. A bare browser renders the file’s mathematics without any ScriptPub JavaScript. On parse, native <math>, TeX-bearing wrappers (MathJax/Wikimedia-style markup with annotations or data-latex), and their image/SVG fallbacks collapse to one atomic object — fallback text is never duplicated into prose.

Rendering and accessibility

A conforming renderer parses TeX and emits native MathML. ScriptPub’s reference engine uses KaTeX’s TeX parser with untrusted commands disabled and emits its MathML-only output, so rendering is SSR-safe and needs no runtime script or font/CSS payload. Native source MathML crosses a DOM boundary only after an allow-list sanitizer removes executable elements, event handlers, URL-bearing styles, and non-MathML markup.

The rendered object has the math role and an accessible label from alt, then latex, then a generic formula label. Native <semantics> / TeX annotations remain available to assistive technology and copy tools. Invalid TeX MUST NOT crash document rendering: the expression renders as an error/fallback MathML node while its source remains intact.

Foreign formats

Converters map math between the object and each foreign format’s own math spelling — Markdown $…$ / $$…$$, EPUB/HTML MathML, DOCX OMML, ODT formula objects; formats with no portable math grammar (Fountain, FDX, plain text) receive the plain projection (alt, then TeX). The per-format details are app documentation, not part of this specification. An importer that encounters a formula image without structural source MAY use its TeX-bearing alt only when the producer identifies it as a math fallback; an arbitrary image alt string is not inferred as mathematics.