feat: migrate from KaTeX to MathJax for enhanced Mathematics and Chemistry rendering
Important Note
This migration from KaTeX to MathJax was initiated due to bugs found in the main branch. While I have now rebased this against dev (where some KaTeX fixes are already present), I am providing this patch as a complete MathJax replacement as an option to the core team.
Pull Request Checklist
Target branch: This PR targets the dev branch.
Description: Concise description provided below.
Changelog: Changelog entry included below.
Documentation: No user-facing docs change needed — this is an internal UI state bug.
Dependencies: Mathjax v4.1.1.
Testing: Manually verified — steps to reproduce the issue and confirm the fix are included below.
Agentic AI Code: This PR was written and reviewed by me.
Code review: Self-reviewed.
Design & Architecture: No new settings introduced.
Title Prefix:feat prefix applied.
Description
This PR migrates the core math rendering engine from KaTeX to MathJax (v4).
While KaTeX provided fast rendering, it frequently struggled with complex LaTeX environments, specifically matrices, alignment, and chemical notation, leading to frequent rendering errors ("black boxes") and tokenizer leaks (orphaned $ symbols).
MathJax provides superior TeX compatibility and better handling of multi-line layouts, which significantly improves the stability of complex document rendering in Open WebUI.
Added
MathJax v4 integration: Replaced KaTeX with MathJax, configured to use SVG output for maximum cross-browser consistency.
Chemistry Support: Enabled the mhchem extension, allowing users to render chemical equations via \ce{}.
Improved Math Tokenization: The \pu{} and \ce{} delimiters was preserved to the markdown tokenizer to support scientific notation and chemical formulas natively.
Changed
src/app.html: Added global MathJax configuration, including ams and mhchem packages.
src/lib/utils/marked/math-extension.ts: Refactored the math tokenizer to prioritize block-mode equations over inline, ensuring correct handling of multi-line environments like matrices.
src/lib/components/chat/Messages/Markdown/MathRenderer.svelte: Replaced KaTeX-specific rendering logic with MathJax’s asynchronous typesetPromise to resolve race conditions and rendering artifacts.
package.json: Added mathjax dependency and katex was removed.
fix:
Fixed: We encountered multiple rendering issues with KaTeX. Migrating to MathJax eliminates these problems, many of which stem from KaTeX's inherent design limitations.
Breaking Change
BREAKING CHANGE: This PR removes the KaTeX dependency. We have reviewed all custom CSS and logic relying on KaTeX-specific class names to ensure compatibility. This transition significantly improves rendering stability for complex scientific content.
Additional Information
Motivation: KaTeX's limited support for certain LaTeX environments (specifically multi-line matrices and chemical notations) often resulted in failed renders in a chat-based LLM environment. Migrating to MathJax aligns Open WebUI with standard academic rendering practices and enables better support for researchers and students.
Testing:
Verified rendering for a wide range of LaTeX expressions (inline and block).
Verified that Markdown syntax inside math environments remains undisturbed.
Screenshots or Videos
A matrix rendering failure (main branch) from KaTeX vs. the stable render in MathJax
Chemical formula
Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.
## 📋 Pull Request Information
**Original PR:** https://github.com/open-webui/open-webui/pull/23791
**Author:** [@jorgeventura](https://github.com/jorgeventura)
**Created:** 4/16/2026
**Status:** ❌ Closed
**Base:** `dev` ← **Head:** `feat-mathjax-dev`
---
### 📝 Commits (6)
- [`5fc8696`](https://github.com/open-webui/open-webui/commit/5fc8696af4881670f19f3bb375303a868df6aee0) Feat: Integrate MathJax support for math rendering
- [`b7366fe`](https://github.com/open-webui/open-webui/commit/b7366fe49bd2d6e2cc5f6757810f1331e4ee7b91) Refactor math delimiter regex for block content
- [`d6edf06`](https://github.com/open-webui/open-webui/commit/d6edf061dc0a9cf8955639f3bd12a518fecfbfa8) Matrices are working
- [`bb95afc`](https://github.com/open-webui/open-webui/commit/bb95afc4c58e8c1adf14b658df7c5bcf7cb8db38) Needs remove $ in excess
- [`40f38ab`](https://github.com/open-webui/open-webui/commit/40f38abf116ba9f69058bc11ddb514aec0ad8d36) The $ excess fixed.
- [`369c55c`](https://github.com/open-webui/open-webui/commit/369c55c5bdf1703e8a42374ce6ff28808b50ec67) feat(math): complete KaTeX to MathJax migration and chemistry support
### 📊 Changes
**12 files changed** (+247 additions, -126 deletions)
<details>
<summary>View changed files</summary>
📝 `package-lock.json` (+16 -1)
📝 `package.json` (+1 -1)
📝 `src/app.css` (+8 -8)
📝 `src/app.html` (+30 -0)
📝 `src/lib/components/chat/Messages/Markdown.svelte` (+2 -2)
➖ `src/lib/components/chat/Messages/Markdown/KatexRenderer.svelte` (+0 -33)
📝 `src/lib/components/chat/Messages/Markdown/MarkdownInlineTokens.svelte` (+3 -3)
📝 `src/lib/components/chat/Messages/Markdown/MarkdownTokens.svelte` (+5 -5)
➕ `src/lib/components/chat/Messages/Markdown/MathRenderer.svelte` (+87 -0)
📝 `src/lib/utils/index.ts` (+24 -9)
📝 `src/lib/utils/marked/math-extension.ts` (+68 -64)
📝 `vite.config.ts` (+3 -0)
</details>
### 📄 Description
---
### Title:
`feat: migrate from KaTeX to MathJax for enhanced Mathematics and Chemistry rendering`
---
#### **Important Note**
**This migration from KaTeX to MathJax was initiated due to bugs found in the main branch. While I have now rebased this against dev (where some KaTeX fixes are already present), I am providing this patch as a complete MathJax replacement as an option to the core team.**
---
# Pull Request Checklist
- [x] **Target branch:** This PR targets the `dev` branch.
- [x] **Description:** Concise description provided below.
- [ ] **Changelog:** Changelog entry included below.
- [ ] **Documentation:** No user-facing docs change needed — this is an internal UI state bug.
- [x] **Dependencies:** Mathjax v4.1.1.
- [x] **Testing:** Manually verified — steps to reproduce the issue and confirm the fix are included below.
- [ ] **Agentic AI Code:** This PR was written and reviewed by me.
- [x] **Code review:** Self-reviewed.
- [x] **Design & Architecture:** No new settings introduced.
- [x] **Title Prefix:** `feat` prefix applied.
---
### Description
- This PR migrates the core math rendering engine from KaTeX to **MathJax (v4)**.
- While KaTeX provided fast rendering, it frequently struggled with complex LaTeX environments, specifically matrices, alignment, and chemical notation, leading to frequent rendering errors ("black boxes") and tokenizer leaks (orphaned `$` symbols).
- MathJax provides superior TeX compatibility and better handling of multi-line layouts, which significantly improves the stability of complex document rendering in Open WebUI.
### Added
- **MathJax v4 integration:** Replaced KaTeX with MathJax, configured to use SVG output for maximum cross-browser consistency.
- **Chemistry Support:** Enabled the `mhchem` extension, allowing users to render chemical equations via `\ce{}`.
- **Improved Math Tokenization:** The `\pu{}` and `\ce{}` delimiters was preserved to the markdown tokenizer to support scientific notation and chemical formulas natively.
### Changed
- **`src/app.html`**: Added global `MathJax` configuration, including `ams` and `mhchem` packages.
- **`src/lib/utils/marked/math-extension.ts`**: Refactored the math tokenizer to prioritize block-mode equations over inline, ensuring correct handling of multi-line environments like matrices.
- **`src/lib/components/chat/Messages/Markdown/MathRenderer.svelte`**: Replaced KaTeX-specific rendering logic with MathJax’s asynchronous `typesetPromise` to resolve race conditions and rendering artifacts.
- **`package.json`**: Added `mathjax` dependency and `katex` was removed.
### fix:
- **Fixed:** We encountered multiple rendering issues with `KaTeX`. Migrating to `MathJax` eliminates these problems, many of which stem from KaTeX's inherent design limitations.
### Breaking Change
- **BREAKING CHANGE**: This PR removes the `KaTeX` dependency. We have reviewed all custom CSS and logic relying on KaTeX-specific class names to ensure compatibility. This transition significantly improves rendering stability for complex scientific content.
---
### Additional Information
- **Motivation:** KaTeX's limited support for certain LaTeX environments (specifically multi-line matrices and chemical notations) often resulted in failed renders in a chat-based LLM environment. Migrating to MathJax aligns Open WebUI with standard academic rendering practices and enables better support for researchers and students.
- **Testing:**
- Verified rendering for a wide range of LaTeX expressions (inline and block).
- Validated complex matrix layouts (e.g., `pmatrix`, `bmatrix`).
- Validated chemistry formulas using `\ce{}`.
- Verified that Markdown syntax inside math environments remains undisturbed.
### Screenshots or Videos
- A matrix rendering failure (main branch) from KaTeX vs. the stable render in MathJax
<img width="2201" height="701" alt="Screenshot_20260414_095333-1" src="https://github.com/user-attachments/assets/24fd681c-ac73-40a3-b2ce-635fa8b65323" />
- Chemical formula
<img width="1078" height="413" alt="Screenshot_20260415_080140" src="https://github.com/user-attachments/assets/8825b565-7317-40f0-bb8b-c6d0aeee3e6b" />
### Contributor License Agreement
- [x] By submitting this pull request, I confirm that I have read and fully agree to the [Contributor License Agreement (CLA)](https://github.com/open-webui/open-webui/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT), and I am providing my contributions under its terms.
---
---
<sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 Pull Request Information
Original PR: https://github.com/open-webui/open-webui/pull/23791
Author: @jorgeventura
Created: 4/16/2026
Status: ❌ Closed
Base:
dev← Head:feat-mathjax-dev📝 Commits (6)
5fc8696Feat: Integrate MathJax support for math renderingb7366feRefactor math delimiter regex for block contentd6edf06Matrices are workingbb95afcNeeds remove $ in excess40f38abThe $ excess fixed.369c55cfeat(math): complete KaTeX to MathJax migration and chemistry support📊 Changes
12 files changed (+247 additions, -126 deletions)
View changed files
📝
package-lock.json(+16 -1)📝
package.json(+1 -1)📝
src/app.css(+8 -8)📝
src/app.html(+30 -0)📝
src/lib/components/chat/Messages/Markdown.svelte(+2 -2)➖
src/lib/components/chat/Messages/Markdown/KatexRenderer.svelte(+0 -33)📝
src/lib/components/chat/Messages/Markdown/MarkdownInlineTokens.svelte(+3 -3)📝
src/lib/components/chat/Messages/Markdown/MarkdownTokens.svelte(+5 -5)➕
src/lib/components/chat/Messages/Markdown/MathRenderer.svelte(+87 -0)📝
src/lib/utils/index.ts(+24 -9)📝
src/lib/utils/marked/math-extension.ts(+68 -64)📝
vite.config.ts(+3 -0)📄 Description
Title:
feat: migrate from KaTeX to MathJax for enhanced Mathematics and Chemistry renderingImportant Note
This migration from KaTeX to MathJax was initiated due to bugs found in the main branch. While I have now rebased this against dev (where some KaTeX fixes are already present), I am providing this patch as a complete MathJax replacement as an option to the core team.
Pull Request Checklist
devbranch.featprefix applied.Description
$symbols).Added
mhchemextension, allowing users to render chemical equations via\ce{}.\pu{}and\ce{}delimiters was preserved to the markdown tokenizer to support scientific notation and chemical formulas natively.Changed
src/app.html: Added globalMathJaxconfiguration, includingamsandmhchempackages.src/lib/utils/marked/math-extension.ts: Refactored the math tokenizer to prioritize block-mode equations over inline, ensuring correct handling of multi-line environments like matrices.src/lib/components/chat/Messages/Markdown/MathRenderer.svelte: Replaced KaTeX-specific rendering logic with MathJax’s asynchronoustypesetPromiseto resolve race conditions and rendering artifacts.package.json: Addedmathjaxdependency andkatexwas removed.fix:
KaTeX. Migrating toMathJaxeliminates these problems, many of which stem from KaTeX's inherent design limitations.Breaking Change
KaTeXdependency. We have reviewed all custom CSS and logic relying on KaTeX-specific class names to ensure compatibility. This transition significantly improves rendering stability for complex scientific content.Additional Information
pmatrix,bmatrix).\ce{}.Screenshots or Videos
Contributor License Agreement
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.