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

Overview

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);

Below, we examine the parts of that code.

In-Browser

To render math in 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);

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.

Server-Side

To generate MathML 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}");

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:

Post Process

The postProcess function implements the AMS functions \ref and \label. 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. If you choose not to support \ref, postProcess can be omitted.

If Temml is used server-side, \ref and \label 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.

If you use the auto-render extension, it includes the post-processor nuances.

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.

Temml-Local.css is the light-weight option. It calls two fonts: Cambria Math, which comes pre-installed in Windows, or STIX TWO, which comes pre-installed in iOS and MacOS (as of Safari 16). Cambria Math lacks roundhand glyphs, so you still have to serve a small (12 kb) font, Temml.woff2, in order to support \mathscr{…}.
Android does not currently provide a font with a MATH table. They are considering several options.

Sadly, native fonts render math with a couple of flaws. In Firefox, square root radicals are sometimes oddly sized. Chromium is better at radicals, but it fails to stretch five stretchy accents and some extensible arrows. Chromium also renders extensible arrows with notes placed too high.

Latin Modern is a clone of Computer Modern and so is very home-like for readers accustomed to LaTeX documents. Rendering is excellent except that some line thicknesses may be too thin for some screens. This option also needs that additional 12kb Temml.woff2 file in order to support \mathscr{…}.

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

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 numbering 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, just use temml.cjs instead of temml.min.js. temml.cjs includes 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 Firefox WebKit (Safari)
Accents✓✓bad1, 2
Wide accents, in general✓✓bad3
\widehat, \widetildepoor4✓✓
Primemeh5✓meh5
Integral, ∫, in display modepoor6✓✓
\left( x \right)meh7✓meh7
\bigg(, \Bigg(, etc.meh8✓meh8
\cancel, \bcancel, \xcancelmeh9meh9meh9
{Vmatrix} environment✓✓poor10
{align} environment✓✓bad11
\mathllap, \mathrlap✓✓bad12
Extensible arrowsbad13✓bad13, 14
Square root radicals✓meh15✓
Line-breaking✓✓bad16

Notes:

  1. WebKit renders normal accents too high. (Extensible accents are set at the correct height.)
  2. WebKit fails to make a italic correction on accents. Many are set too far left.
  3. WebKit fails to stretch many wide accents.
  4. Chromium does not stretch \widehat or \widetilde.
  5. Chromium and WebKit fail to properly address italic correction on prime. So f ′ overlaps.
  6. Chromium does not stretch a system font ∫ in display mode. Latin Modern is okay.
  7. Chromium and WebKit set parentheses too high for \left( x \right).
  8. Chromium and WebKit set \bigg(, \Bigg(, etc., at the wrong vertical alignment.
  9. Because Chromium does not support <enclose>, Temml uses background images for \cancel. It may not print properly.
  10. WebKit does not stretch the delimiters for {Vmatrix}.
  11. WebKit renders the {align} environment remarkably poorly.
  12. WebKit does not render laps properly.
  13. Chromium and WebKit system font extensible arrows have notes placed too high. Some do not stretch. Again, Latin Modern is okay.
  14. WebKit fails to stretch most extensible arrows.
  15. Firefox sometimes selects radicals that are too tall.
  16. Automatic linebreaking (non-display mode) works in Chromium and Firefox. Not in WebKit.

Another issue if you are targeting mobile: Android has not provided a math system font. They are planning to add a MATH table to the Noto Sans font. I don’t think it has shipped.

You can view all these issues for yourself at the Temml function support page.

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


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