Temml Administration

Browser Support

Temml works in browsers that support MathML. This includes Chrome, Edge, Firefox, and Safari. Temml will never work in Internet Explorer.

Installation

For use in the browser, you can download a zip file of Temml from the releases page of the Temml repository. For server-side use, you can obtain Temml via CLI commands npm install temml or yarn add temml.

The minimum browser installation needs the following files. The css file and font file must be in the same folder.

A server-side installation should use temml.cjs or temml.mjs instead of temml.min.js.

Starter template

<!DOCTYPE html>
<!-- Temml requires the use of the HTML5 doctype. -->
<html>
    <head>
        ...
        <link rel="stylesheet" href="./Temml-Local.css">
        <script src="./temml.min.js"></script>
    </head>
    ...
</html>

API

In-Browser, One Element

To render one <math> element into one DOM element, call temml.render with a TeX expression and a DOM element to render into:

temml.render("c = \\pm\\sqrt{a^2 + b^2}", element);

To render in display mode, the call would be:

temml.render("c = \\pm\\sqrt{a^2 + b^2}", element, { displayMode: true });

If the element you provide is a <math> element, Temml will populate it. Otherwise, it will create a new <math> element and make it a child of the element you provide.

In-Browser, Bulk

Breaking Change Notice: renderMathInElement is now part of temml.js. No extension is necessary.

The renderMathInElement function is typically used to render all of the math in the text of a running HTML document. It searches all of the text in a given element for your chosen delimiters, and renders the math in place.

A typical call might look like this:

<script>
   temml.renderMathInElement(document.main, { fences: "$+" })
</script>
Auto-render details

In an auto-render document, authors write LaTeX within math delimiters. The default delimiters are:

The items beginning with \begin{equation} and ending with \eqref{…} are from AMS LaTeX.

You can use the fences option to customize the recognized delimiters.

fences
key		 $$…$$ $`…`$ $…$ \[…\] \(…\) AMS
default✓✓✓✓
$✓✓✓
$+✓✓✓✓
(✓✓
(+✓✓✓
ams✓
all✓✓✓✓✓✓
…or you can use the delimiters option instead of the fences option to further customize your delimiters:

The property of a delimiters option is a detailed list of delimiters. Here is the default:

delimiters: [
  { left: "$$", right: "$$", display: true },
  { left: "\\(", right: "\\)", display: false },
  { left: "\\begin{equation}", right: "\\end{equation}", display: true },
  { left: "\\begin{equation*}", right: "\\end{equation*}", display: true },
  { left: "\\begin{align}", right: "\\end{align}", display: true },
  { left: "\\begin{align*}", right: "\\end{align*}", display: true },
  { left: "\\begin{alignat}", right: "\\end{alignat}", display: true },
  { left: "\\begin{alignat*}", right: "\\end{alignat*}", display: true },
  { left: "\\begin{gather}", right: "\\end{gather}", display: true },
  { left: "\\begin{gather*}", right: "\\end{gather*}", display: true },
  { left: "\\begin{CD}", right: "\\end{CD}", display: true },
  { left: "\\[", right: "\\]", display: true }
];

If you want to add support for inline math via $…$, be sure to list it after $$…$$. Because rules are processed in order, putting a $ rule first would match $$ and treat as an empty math expression.

The renderMathInElement function recognizes an options object as it’s second argument. This is demonstrated above with fences. The options argument can include any option used by the temml.render function. It also recognizes fences or delimiters and the following options:

Server-Side

To generate a <math> element on the server or to generate an MathML string of the rendered math, you can use temml.renderToString:

const temml = require('./temml.cjs');  // if in Node.js
const mathML = temml.renderToString("c = \\pm\\sqrt{a^2 + b^2}");

...and for display mode:

const mathML = temml.renderToString("c = \\pm\\sqrt{a^2 + b^2}", { displayMode: true });

Macro persistence

Authors can write their own macros, but you decide whether macros should persist between calls to temml.render.

Say that you have an HTMLCollection of elements whose contents should be converted from TeX strings to math. The code for such a conversion might look like this:

Option 1: Macros do not persist between calls to Temml:

// Render all the math.
for (let aSpan of [...mathSpans]) {
    const tex = aSpan.textContent;
    const displayMode = aSpan.classList.contains("display");
    temml.render(tex, aSpan, { displayMode });
}
// Optional postProcess to render \ref{}
temml.postProcess(document.body);
Option 2: Macros defined with \gdef do persist: 
// Optional macros object to hold macros that persist between calls to Temml.
const macros = {}
// Render all the math.
for (let aSpan of [...mathSpans]) {
    const tex = aSpan.textContent;
    const displayMode = aSpan.classList.contains("display");
    // Notice the macros argument below.
    // It carries macros that were defined with \gdef or \global\let
    temml.render(tex, aSpan, { macros, displayMode });
}
// Optional postProcess to render \ref{}
temml.postProcess(document.body);

Notice that you can choose when to stop macro persistence by redefining macros.


Option 3: Macros persist and there are some predefined macros:

Now say that you wish to pre-define two macros and a color with document-wide scope.

// Optional preamble to pre-define macros.
const macros = temml.definePreamble(
    `\\newcommand\\d[0]{\\operatorname{d}\\!}
    \\def\\foo{x^2}
    \\definecolor{sortaGreen}{RGB}{128,128,0}`
);
// Render all the math.
for (let aSpan of [...mathSpans]) {
    const tex = aSpan.textContent;
    const displayMode = aSpan.classList.contains("display");
    temml.render(tex, aSpan, { macros, displayMode });
}
// Optional postProcess to render \ref{}
temml.postProcess(document.body);

Preamble

To give document-wide scope to a set of macros or colors, define them in a preamble.

const macros = temml.definePreamble(
    `\\newcommand\\d[0]{\\operatorname{d}\\!}
    \\def\\foo{x^2}
    \\definecolor{sortaGreen}{RGB}{128,128,0}`
);

Any valid Temml macro or \definecolor may be written into a preamble. Then include the resulting macros in the Temml options.

Options

You can provide an object of options as the last argument to temml.render and temml.renderToString. For example:

temml.render(
  "c = \\pm\\sqrt{a^2 + b^2}",
  element, 
  { displayMode: true,  macros }
);
Available options are:

\ref and \eqref

If you are using temml.renderMathInElement, you can ignore this section. renderMathInElement handles this automatically.

The postProcess function implements the AMS functions \ref and \eqref. It should be called outside of any loop.

The main Temml functions, temml.render and temml.renderToString, each operate on only one element at a time. In contrast, the postProcess function makes two passes through the entire document. One pass finds the \labels written in a document and the second pass populates \ref and \eqref with the tags or auto-numbers associated with each label.

If you choose not to support \ref and \eqref, postProcess can be omitted.

If Temml is used server-side, \ref and \eqref are still implemented at runtime with client-side JavaScript. A small file, temmlPostProcess.js, is provided to be installed in place of temml.min.js. It exposes one function:

temml.postProcess(document.body)

If you do not provide a runtime postProcess, everything in Temml will work except \ref and \eqref.

Version

To get the current version of Temml running in the browser, open the console and type:

temml.version

Fonts

Temml has several different pre-written CSS files. You should use only one and by that choice, you also choose a math font. There are several math fonts available and each has different advantages.

Latin Modern will provide the best quality rendering. It is a clone of Computer Modern and so is very home-like for readers accustomed to LaTeX documents. For best results, you must also serve a small (10kb) Temml.woff2 file. Then you’ll get support for \mathscr{…} and you’ll get primes at the correct vertical alignment in Chrome and Edge.

Temml-Local.css is the light-weight option. It calls three fonts: Cambria Math, which comes pre-installed in Windows, STIX TWO, which comes pre-installed in iOS and MacOS (as of Safari 16), or NotoSans Math, which I think comes pre-installed in Android. The first two need to be augmented with Temml.woff2.

Sadly, this option has rendering issues. Chrome botches extensible arrows and it will fail to stretch the ∫ symbol on Windows.

Asana and Libertinus have some of the same rendering problems as Cambria Math, although Asana does contain its own roundhand glyphs.

NotoSans Math is a sans-serif math font from Google. I think it comes bundled with Android. Chromium fails to stretch extensible arrows in this font. NOTE: Temml’s NotoSans CSS file calls the ttf version of the font, not the woff2 version. The woff2 version has many rendering issues.

Several other math fonts exist and you can try them out at Frédéric Wang’s Mathematical OpenType Fonts.

Where to find font files:

If you want a different math font size, you can add a rule to your own page’s CSS, like this example:

math { font-size: 125%; }

Equation numbering

In order to place automatic equation numbers in certain AMS environments, Temml contains these CSS rules:

.tml-eqn::before {
  counter-increment: tmlEqnNo;
  content: "(" counter(tmlEqnNo) ")";
}
body { counter-reset: tmlEqnNo; }

You can overwrite the content rule to produce customized equation numbers. For instance, if chapter three of your book is in its own html file, that file’s <head> could contain:

<style>
   .tml-eqn::before { content: "(3." counter(tmlEqnNo) ")"; }
</style>

Then the automatic equation numbering in that chapter would look like: (3.1)

If your site does not render automatic numbering properly, check if your other CSS has overwritten the Temml counter-reset.

Extensions

More Temml functionality can be added via the following extensions:

To install extensions for browser use, include the appropriate file from the contrib folder of the Temml repository. Then reference the file in the <head> of the HTML page. As in this mhchem example:

  <head>
    ...
    <link rel="stylesheet" href="./Temml-Local.css">
    <script src="./temml.min.js"></script>
    <script src="./mhchem.min.js"></script>
  </head>

The extension reference must come after the reference to temml.min.js.

For server-side use, use temml.cjs or temml.mjs instead of temml.min.js. temml.cjs and temml.mjs both include mhchem, physics, and texvc.

Security

Any HTML generated by Temml should be safe from <script> or other code injection attacks.

A variety of options give finer control over the security of Temml with untrusted inputs; refer to Options for more details.

Browser Issues

If you are deciding whether to render math in MathML, know that all the major browser engines now support MathML. If you want to revel in the sight of over a thousand LaTeX functions rendered well in MathML, head on over to the Temml function support page.

The rest of you, stay here. This section identifies functions that browsers render poorly.

Item Chromium Gecko
(Firefox)		 WebKit
(Safari)		 Examples
Renders well on first paint✓✓bad¹E→
Accents✓✓bad²𝖺^
Integral, ∫, in display modemeh³✓✓∫ab
\left( x \right)✓✓meh⁴(x)
Tag placement✓✓poor⁵

x(tag)

Extensible arrowspoor⁶✓poor⁶A⇀noteB
Radical height✓meh⁷meh⁷fc
Size 4 radicalsmeh⁸✓✓
Line-breaking✓✓bad⁹

\smash, \mathllap, \mathrlap,
CD environment		✓✓bad¹⁰xyz
Flattened circumflex accentpoor¹¹poor¹¹poor¹¹a^
Stretchy parentheses in NotoSans Mathbad¹²✓bad¹²

Notes:

  1. WebKit renders some things correctly only after a page refresh.

  2. WebKit renders some accents too high. Temml does some work to mitigate this. It’s not enough.

  3. Chromium does not stretch a Cambria Math ∫ in display mode. Latin Modern is okay.

  4. WebKit mis-aligns short parentheses, given a \left and \right.

  5. WebKit mis-locates tags and AMS automatic equation numbers because it ignores width: 100% on an <mtable>.

  6. Chromium and WebKit system font extensible arrows have notes placed too high. Some do not stretch in Cambria Math or NotoSans. Again, Latin Modern is okay.

  7. Firefox and WebKit sometimes select radicals that are too tall. (Root cause: They don’t cramp subscripts and superscripts.)

  8. In very tall radicals, Chromium does not accurately match the vinculum to the surd.

  9. Automatic linebreaking (non-display mode) works in Chromium and Firefox. Not in WebKit.

  10. WebKit fails to render anything inside the <mpadded> element.

  11. All browsers fail to flatten a circumflex accent in any font other than Latin Modern.

  12. Chromium does not stretch delimiters in NotoSans Math. WebKit does not stretch parentheses or arrows.

You can suggest revisions to this page at the Temml issues page.


Copyright © 2021-2025 Ron Kok. Released under the MIT License