Reference Math

Annotated source

A fenced code block with the language math is display math:

mdsvex({ math: {} });
You write
```math
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
```

You get
Compiles to
<div
  class="math math-display"
  translate="no"
>
  <math
    display="block"
    class="tml-display"
    style="display:block math;"
    ><mrow
      ><msubsup
        ><mo movablelimits="false">∫</mo
        ><mn>0</mn><mi>∞</mi></msubsup
      ><msup
        ><mi>e</mi><mrow
          class="tml-sml-pad"
          ><mo
            form="prefix"
            stretchy="false"
            lspace="0em"
            rspace="0em">−</mo
          ><msup
            ><mi>x</mi><mn
              class="tml-sml-pad">2</mn
            ></msup
          ></mrow
        ></msup
      ><mspace width="0.1667em"
      ></mspace><mi>d</mi><mi>x</mi><mo
        >=</mo
      ><mfrac
        ><msqrt
          ><mrow
            ><mi>π</mi><mspace
              width="0pt"
              height="0.5em"
            ></mspace></mrow
          ></msqrt
        ><mn>2</mn></mfrac
      ></mrow
    ></math
  >
</div>

The Vite plugin renders the LaTeX when it compiles the document, with Temml, into MathML. Browsers draw MathML themselves, so the page loads no JavaScript for math.

There is no <pre> or <code> around it, and the fence never reaches the highlighter, whatever highlight is. Braces in the LaTeX need no escaping. mdsvex makes the output safe for Svelte, whichever renderer produced it. The <div> is there because MathML takes no translate attribute of its own, and it gives you something to style.

Temml loads the first time a document has math, so a site without math never loads it. Anything after math on the fence line is kept, and is reserved for later use. Nothing reads it today, apart from a math component.

On the atlas: math.

Inline math is a code span wrapped in dollars, on one line:

You write
Euler's identity, $`e^{i\pi} + 1 = 0`$, links five constants.

You get
Compiles to
<p>
  Euler's identity, <span
    class="math math-inline"
    translate="no"
    ><math
      ><mrow
        ><msup
          ><mi>e</mi><mrow
            class="tml-sml-pad"
            ><mi>i</mi><mi>π</mi></mrow
          ></msup
        ><mo>+</mo><mn>1</mn><mo>=</mo
        ><mn>0</mn></mrow
      ></math
    ></span
  >, links five constants.
</p>

Both dollars have to touch the backticks. The LaTeX is raw, as in the fence, and there is no <code> around the result. It works wherever a code span does: in a heading, a list, a table cell or the text of a link. GitHub and GitLab render the same source as math.

  • In a table cell write the LaTeX double bar as \Vert, since \| there is an escaped cell bar.

Only these two forms are math. A latex or tex fence is a code block that shows its source. $…$ and $$…$$ are plain text, so a price such as $5 needs no escaping, and a $ beside a code span that the other $ doesn't follow is a $ ($`x` is a dollar and inline code). Inline code with the hint, `#!math x^2`, is plain inline code.

You write
It costs $5, and $x$ and $$x$$ are text. $`x` is a dollar and inline code.

You get
Compiles to
<p>
  It costs $5, and $x$ and $$x$$ are
  text. $<code>x</code> is a dollar and inline
  code.
</p>

mdsvex adds no CSS. Temml's stylesheet is in the temml package, so add it to your own dependencies and import the stylesheet once, usually in your root layout:

npm i --save-dev temml
import 'temml/dist/Temml-Local.css';

Temml-Local.css uses a math font the reader already has. It asks for Cambria Math, then STIX Two Math, then Noto Sans Math, then the browser's own math font. The only font it loads is a 9 KB one for script capitals. Without the stylesheet the math still renders, but spacing and a few constructs differ between browsers.

The package also has Temml-Latin-Modern.css, Temml-Asana.css, Temml-STIX2.css, Temml-Libertinus.css and Temml-NotoSans.css, one for each web font. Each expects its font file beside it, and the package doesn't include those fonts. Copy the stylesheet and the font into your project, as Temml's documentation describes.

A wide equation can be wider than the page. Let it scroll:

.math-display {
	overflow-x: auto;
}

KaTeX renders HTML that it lays out with its own fonts, with MathML beside it for screen readers. It looks the same in every browser, and it is several times more markup than MathML alone. Install it yourself and pick it:

npm i --save-dev katex
mdsvex({ math: { renderer: 'katex' } });
import 'katex/dist/katex.min.css';

KaTeX needs its stylesheet. Without it the reader sees every equation twice.

  • Picking 'katex' without the package installed is an error that names the package.

options is passed to the renderer, Temml's options or KaTeX's:

mdsvex({
	math: {
		options: {
			macros: { '\\RR': '\\mathbb{R}' }
		}
	}
});

mdsvex sets displayMode itself. It also sets throwOnError, so that LaTeX the renderer can't read fails the build. Pass throwOnError: false to draw the error in the page instead.

With Temml, annotate: true adds the LaTeX to the MathML as an annotation. KaTeX always adds it.

  • A definition made in a fence with \gdef ends with that fence. Documents compile in no fixed order, so a definition that leaked from one into the next would work on some builds and not on others. Put shared definitions in macros.

LaTeX the renderer can't read is a MathError. The message names the file and the line of the fence or of the inline math, and line and column point at the place in the LaTeX when the renderer says where it is, so Vite's error overlay opens on it:

You write src/routes/post.svx
```math
\frac{a}{
```

Its compile throws

Error Unexpected end of input in a macro argument, expected '}' at end of input: \frac{a}{ (`math` fence at /src/routes/post.svx:1)

You write src/routes/post.svx
A fraction, $`\frac{a}{`$.

Its compile throws

Error Unexpected end of input in a macro argument, expected '}' at end of input: \frac{a}{ (inline math at /src/routes/post.svx:1)

cause is the renderer's own error.

A math export in a components module replaces math. It gets these props:

propvalue
childrenthe rendered math, the same <div class="math math-display"> or <span class="math math-inline"> it renders as without a replacement
codethe LaTeX, as written
displaytrue for a fence, not passed for inline math
metathe rest of the fence line, raw, when there is any
src/lib/markdown.js
export { default as math } from './markdown/Math.svelte';

The same component gets both kinds, so one that draws a block around the math does so only when display is set.

With component_mode: 'all', a <math> element you type yourself goes to the same component, with its attributes as props and no code.

  • A pre or code replacement never gets math, and a math replacement never gets code. With math: false a math fence is a code block again, so it goes to pre, and inline math is inline code that shows the LaTeX, so it goes to code.
  • The MathML a renderer made is never replaced, in either mode.

A button that copies the LaTeX of a fence:

src/lib/markdown/Math.svelte
<script>
	let { code, display = false, children } = $props();
</script>

{#if display}
	<figure class="equation">
		{@render children()}
		<button onclick={() => navigator.clipboard.writeText(code)}>copy LaTeX</button>
	</figure>
{:else}
	{@render children()}
{/if}

See the math playground example.

math can be a function instead of options. It gets the LaTeX and returns markup, such as MathML, HTML or SVG:

mdsvex({
	math: (latex, { display, meta, filename }) => render_somehow(latex, display)
});

display is true for a fence and false for inline math, and meta is the rest of the fence line, empty for inline math. It doesn't escape anything for Svelte. mdsvex does that, and puts the result in the <div> or the <span>.

  • It must be synchronous, and it should throw when it can't render, which mdsvex reports as a MathError.

compile is synchronous and loads nothing, so a math fence is a code block and inline math is inline code unless you pass math. load_math from mdsvex/math imports the renderer and takes the same object as the plugin option:

import { compile } from 'mdsvex/compile';
import { load_math } from 'mdsvex/math';

const math = await load_math({ options: { annotate: true } });

const { code } = compile(source, { math, filename: 'post.svx' });

Where you can't await, import the library yourself and pass it to temml_math or katex_math:

import temml from 'temml';
import { temml_math } from 'mdsvex/math';

const math = temml_math(temml, { annotate: true });

compile also takes a renderer function, or false.

The editor reads the option from the manifest the plugin writes, or from math in an mdsvex.config.json, and reports LaTeX that Temml can't read as you type. With KaTeX or a function it doesn't check the LaTeX.

Back to page index

mdsvex, markdown with Svelte in it. MIT licence.