Build your personal knowledge base with Trilium Notes
Math
TeX equations, rendered with KaTeX (what Trilium configures) or MathJax. An equation is either an
inline mathtex-inline widget or a block mathtex-display one, both carrying the source in an
equation attribute. Editing happens in a balloon dialog backed by a MathLive <math-field>, with
a plain LaTeX textarea beside it and a live preview.
Load the Math glue plugin; it pulls in MathEditing and MathUI. AutoformatMath is separate
and opt-in — it turns $$ or \[ at the start of a block into an equation prompt.
Files
| File | Role |
|---|---|
math.ts |
Glue plugin; also declares the ckeditor5 module augmentation, including the math config key |
math_editing.ts |
Schema, conversion, the math command, and the data-processor hook that preserves newlines |
math_command.ts |
The math command — inserts or updates an equation |
math_ui.ts |
Toolbar button, Ctrl+M, and the balloon that hosts the form |
main_form_view.ts |
The dialog: input, display toggle, preview, save/cancel |
math_input_view.ts |
The MathLive <math-field> and LaTeX textarea, kept in sync |
math_view.ts |
The rendered preview |
autoformat_math.ts |
The $$ / \[ shorthand |
utils.ts |
Delimiter helpers, renderEquation, balloon positioning |
typings_external.ts |
Types for KaTeX and MathJax, which are read off globals |
Styling
theme/math_form.css draws the dialog from CKEditor's tokens, and a theme draws over it (the Next
theme does so in theme-next/forms.css and theme-next/notes/text.css). MathLive renders its
field and its menu in the math field's shadow root, which a theme reaches only through ::part()
and MathLive's --ui-* variables. As ::part(menu-item) also matches the headings and the cells
of the matrix and color grids, and no part reaches a color swatch's color or a checkmark,
MathInputView adopts a stylesheet into that root that reads the look of the menu rows, headings,
checkmarks and swatches from variables of its own:
| Variable | Default (MathLive's own) |
|---|---|
--ck-math-menu-item-margin |
0 6px |
--ck-math-menu-item-padding |
1px 7px |
--ck-math-menu-item-border-radius |
4px |
--ck-math-menu-heading-margin |
0.5em 6px 0 |
--ck-math-menu-heading-padding |
1px 7px |
--ck-math-menu-heading-border |
none (a bottom border) |
--ck-math-menu-heading-opacity |
0.5 on the row, 0.4 on its label |
--ck-math-menu-heading-font-size |
inherited |
--ck-math-menu-heading-font-weight |
bold |
--ck-math-menu-heading-letter-spacing |
inherited |
--ck-math-menu-heading-text-transform |
none |
--ck-math-menu-heading-color |
inherited |
--ck-math-menu-checkmark-order |
0 (before the label; 1 puts it after) |
--ck-math-menu-checkmark-margin-inline |
-4px -11px |
--ck-math-menu-checkmark-color |
inherited |
--ck-math-menu-checkmark-indent |
12px (the labels' room for a leading checkmark) |
--ck-math-menu-swatch-size |
2rem |
--ck-math-menu-swatch-gap |
18px (the grid keeps its four columns) |
--ck-math-menu-swatch-background |
var(--neutral-200), var(--neutral-100) when active |
--ck-math-menu-swatch-border-radius |
50%, 2px when active |
--ck-math-menu-swatch-shadow |
none |
The same stylesheet fixes the tooltips of the keyboard and menu toggles above them with CSS anchor
positioning, flipping them below when there is no room, as the scrolling field would clip them.
Where position-area is unsupported, they keep MathLive's placement.
Storage formats
Which one is produced depends on config.math.outputType (Trilium uses span):
span—<span class="math-tex">\(x^2\)</span>, display equations use\[…\]script—<script type="math/tex">x^2</script>, display usesmath/tex; mode=display
Upcast is deliberately more permissive than downcast: it also reads Quill's
<span class="ql-formula" data-value="…">, so content pasted from other editors survives.
Rendering
renderEquation supports KaTeX, MathJax 2, MathJax 3 and a caller-supplied function, and finds the
engine on window rather than importing it — Trilium loads KaTeX lazily via config.math.lazyLoad
and the loader runs at most once (window.CKEDITOR_MATH_LAZY_LOAD caches the promise). Note the
custom-function engine is handed the target element directly and skips preview handling
entirely, so no preview element is created on that path.
Known rough edges
Longstanding, preserved deliberately; none are regressions from the move into this package.
- The
valuebinding on the input is fragile.MathUIbindsmathInputView#valueto the command, butMathInputViewassigns its ownvaluewhenever the MathLive field or the textarea reports a change. Writing a bound property directly severs the binding, so from the first edit onward the form no longer tracks the command._addFormView()compensates by pushing the command's equation in by hand each time the dialog opens — that assignment looks redundant with the binding but is not. - The preview element is never hidden or removed by hand. Both
MathUI#destroy()and_removeFormView()look it up withgetElementByIdafter the form view has already been destroyed or removed from the balloon, and the preview lives inside that view — so the lookup finds nothing. Harmless, because the element goes away with its parent, but the code reads as if it does something. AutoformatMathsetscommand.display = truebefore opening the dialog, butMathCommandrecomputesdisplayfrom the selection on the next model change, which lands first. Typing$$may therefore open the dialog in inline rather than display mode.
Provenance
Vendored, then reworked.
Forked from isaul32/ckeditor5-math by Sauli Anto,
ISC licensed — see LICENSE next to this file. ISC is permissive and combines with
this repository's AGPL-3.0-or-later license.
It is not tracked against upstream and could not easily be: the source was ported to TypeScript and
through several CKEditor 5 API renames, the MathLive-based input view and its preview are Trilium's
own, and Trilium added the \gdef macro isolation and offline font bundling.
It lived at packages/ckeditor5-math until it was folded into this package, which had always been
its only consumer. Points worth recording from that move:
- The package's
mathliveand@ckeditor/ckeditor5-iconsdependencies moved to this package — they are the only runtime dependencies the math feature needs, and MathLive is by far the heaviest thing the editor bundles. math_input_view.tsused to re-declarewindow.mathVirtualKeyboard. MathLive declares it itself; the duplicate was harmless in a separate package but collides here, so it is gone.- The AutoMath paste feature was removed before the move (see 5f833734c2): it listened for
inputTransformationon theClipboardfacade rather thanClipboardPipeline, so it had never fired, and once fixed it proved too narrow to keep. - The package's
tsconfig.test.jsonreferenced an uninstalled@types/mocha, so nothing ever typechecked its tests. Being in this package, they are typechecked now.