Math and equations

Word stores equations as OMML (Office Math Markup Language). Tiptap uses LaTeX notation rendered by KaTeX. The conversion pipeline currently supports export but not import.

What you need

• Extensions: @tiptap/extension-mathematics (not in StarterKit)
• Dependencies: katex (^0.16.4) for rendering

npm install @tiptap/extension-mathematics katex

Support overview

Import

Math equations are not imported on either the editor extension or the REST API.

The DOCX import converter does not include any OMML parsing. When the parser encounters math markup in the document XML, it does not recognize the elements and skips them entirely. No inlineMath or blockMath nodes are produced.

If your workflow requires importing math from DOCX, you would need to build OMML parsing and OMML-to-LaTeX conversion from scratch. There is no existing math infrastructure in the import converter to extend.

Editor rendering

The Mathematics extension provides two node types. It is not included in StarterKit.

The extension provides:

• inlineMath renders within text. Type $$E = mc^2$$ to create via input rule.
• blockMath renders as a standalone block. Type $$$\sum_{i=1}^{n} x_i$$$ to create via input rule.

Both store content as LaTeX strings in a latex attribute and render using KaTeX.

import { Mathematics } from '@tiptap/extension-mathematics'
import 'katex/dist/katex.min.css'

const editor = new Editor({
  extensions: [
    StarterKit,
    Mathematics,
  ],
})

Without the Mathematics extension, math nodes are not recognized by the schema. See the invalid schema guide.

Export

Export math equations using the editor extension or the REST API. Both handle math identically, converting LaTeX to OMML.

The export converter reads the latex attribute from both inlineMath and blockMath nodes and converts the LaTeX into OMML-compatible math components for the DOCX file.

Supported LaTeX features:

If a LaTeX string cannot be parsed, the converter falls back to a plain math run containing the raw LaTeX text.

blockMath nodes export as a standalone paragraph containing a math element. inlineMath nodes export as math elements within the parent paragraph alongside regular text runs.