# Formulas (LaTeX)

> Write LaTeX formulas with MathExtension and your own KaTeX 0.18.2 or newer, then draw them on published pages with renderMath.

URL: https://editor.vivepdf.com/en/docs/formulas/
Last updated: 2026-11-01

The formula extension lets writers type LaTeX and see it drawn by [KaTeX](https://katex.org) while they edit. The editor stores only the LaTeX source, never the drawing, so the saved HTML stays small and clean. On the published page you draw the formulas again with `renderMath`.

Formulas ship as npm packages only. The one-script build does not include them.

## Set it up

1. Install the extension, the UI and KaTeX: `npm install @viveeditor/ext-math @viveeditor/ui @viveeditor/core katex`.
2. Add `MathExtension` with a `load` function that imports KaTeX. KaTeX then downloads only when a formula is shown.
3. Import KaTeX's stylesheet and the extension's stylesheet.
4. Add `mathTools()` to the `plugins` of `createUI` for the `/` menu entries.

```ts
import { Editor } from '@viveeditor/core'
import { basicExtensions } from '@viveeditor/ext-basic'
import { MathExtension } from '@viveeditor/ext-math'
import { createUI } from '@viveeditor/ui'
import { mathTools } from '@viveeditor/ui/extras'
import '@viveeditor/ext-math/style.css'
import 'katex/dist/katex.min.css'

const editor = await Editor.create(document.querySelector('#editor'), {
  extensions: [
    ...basicExtensions,
    MathExtension.configure({
      load: () => import('katex'),
      onError: (error) => console.warn(error.code, error.version),
    }),
  ],
})

createUI(editor, { plugins: [mathTools()] })
```

## KaTeX version

KaTeX must be **0.18.2 or newer** (`MIN_KATEX_VERSION`). The floor follows the KaTeX security advisory GHSA-238p-pmpm-9mq7. An older version is refused and the formula's source is shown instead of a drawing.

`onError` receives an error with one of two codes:

| Code | Meaning |
| --- | --- |
| `KATEX_OUTDATED` | The loaded KaTeX is older than 0.18.2; `version` holds its version. |
| `KATEX_LOAD` | The `load` function failed. |

The editor passes fixed options to KaTeX, including `trust: false`, so a formula cannot add links or other HTML.

## Writing formulas

- **Inline:** type `$x^2$`. When you type the closing `$`, the text between the dollars becomes a formula. It must not start or end with a space.
- **Block:** type `$$` on an empty line and press `Enter`.
- **Menu:** pick "Formula" or "Block formula" from the `/` menu. These entries come from `mathTools()`.
- **Edit:** click a formula, or select it and press `Enter`, to edit its source with a live preview. `Enter` finishes an inline formula, `Ctrl+Enter` (`⌘+Enter` on a Mac) finishes a block formula, and `Esc` leaves without changes.

From code, `editor.commands.insertMath({ display: true, latex: 'E = mc^2' })` inserts a block formula. Leave out `display` for an inline one.

A formula holds at most 2,000 characters (`MAX_LATEX_LENGTH`) and at most 64 levels of nested braces.

## What is stored

```html
<p>Area: <span data-math="inline">\pi r^2</span></p>
<div data-math="block">\int_0^1 x\,dx</div>
```

[The server sanitizer](https://editor.vivepdf.com/en/docs/server-sanitizing/) keeps formulas in exactly this form. A formula that fails its check, or one placed inside a link or a footnote, is reduced to its text.

When the text is saved as Markdown, formulas are written as `$…$` and `$$` blocks. When it is saved as Word, the LaTeX source is written in a code font.

## Published pages

Call `renderMath` on the element that holds the content. It loads KaTeX the same way and returns the number of formulas it drew. The page needs KaTeX's stylesheet too.

```ts
import { renderMath } from '@viveeditor/ext-math/render'
import 'katex/dist/katex.min.css'

const article = document.querySelector('article')
if (article) await renderMath(article, { load: () => import('katex') })
```

- It draws at most 1,000 formulas per call, in batches, so long pages stay responsive.
- Formulas already drawn are skipped, so calling it again is safe.
- Each drawn formula gets its LaTeX source as `aria-label`.

## Related pages

- [Server sanitizing](https://editor.vivepdf.com/en/docs/server-sanitizing/)
- [Footnotes](https://editor.vivepdf.com/en/docs/footnotes/)
- [Open, save and print](https://editor.vivepdf.com/en/docs/open-save-print/)

## Does viveEditor include KaTeX?

No. KaTeX is your own dependency. You pass a load function, and the editor refuses versions older than 0.18.2.

## Is the drawn formula saved?

No. Only the LaTeX source is stored. Published pages draw it again with renderMath.