Mathematics extension

This extension allows you to write and visualize even complex mathematical formulas or equations in your editor. Please note that the current version is still in a very basic stage.

Install

npm install @tiptap-pro/extension-mathematics katex

Additional Setup

You are free to style the rendering element and the editor input.

Import of KaTeX styling (needed).

import 'katex/dist/katex.min.css'

The following classes allow you to select and style the math-decorations. For an example, see demonstration code at the end of this page.

/* Decoration containing the actual text */
.Tiptap-mathematics-editor {
  // …
}

/* Container of the KaTeX rendering */
.Tiptap-mathematics-render {
  // …
}

Control when to render LaTeX decorations

By default LaTeX decorations for mathematical expressions are rendered when said expression is not inside a code block. If you want to customize this behavior, you can do so by passing a function to the shouldRender option. This function should return a boolean value indicating whether the LaTeX decorations should be rendered or not.

import Mathematics from '@tiptap-pro/extension-mathematics'

// [...]

Mathematics.configure({
  shouldRender: (state, pos, node) => {
    const $pos = state.doc.resolve(pos)
    return node.type.name === 'text' && $pos.parent.type.name !== 'codeBlock'
  }
})

You can also import the default shouldRender function to extend the default behavior:

import Mathematics, { shouldRender } from '@tiptap-pro/extension-mathematics'

// [...]

Mathematics.configure({
  shouldRender: (state, pos, node) => {
    // this will disable rendering for headings & code blocks
    return shouldRender(state, pos, node) && node.type.name !== 'heading'
  }
})

Settings

regex

Tiptap needs to know when the text is mathematical. Therefor a regular expression pattern allows us to define this shorthand. E.g. using the TeX shorthand $ … $ (see default below). Matches become decorated – they are not stored as own nodes or marks!

Default: /\$([^\$]*)\$/gi

katexOptions

For the math typesetting the extension uses the third party library KaTeX. To adjust its behaviour, you can pass KaTeX options to it. Find all of them here.

Default: undefined

import Mathematics from '@tiptap-pro/extension-mathematics'

// [...]

Mathematics.configure({
  katexOptions: {
    maxSize: 300,
  },
})

shouldRender

By default LaTeX decorations for mathematical expressions are rendered when said expression is not inside a code block. If you want to customize this behavior, you can do so by passing a function to the shouldRender option. This function should return a boolean value indicating whether the LaTeX decorations should be rendered or not.

Default: () => true

import Mathematics from '@tiptap-pro/extension-mathematics'

// [...]

Mathematics.configure({
  shouldRender: (state, pos, node) => {
    const $pos = state.doc.resolve(pos)
    return node.type.name === 'text' && $pos.parent.type.name !== 'codeBlock'
  }
})