github-starred/open-webui
2
0
Fork 0
mirror of https://github.com/open-webui/open-webui.git synced 2026-05-06 10:58:17 -05:00
Code Issues 1.2k Packages Projects Releases 126 Wiki Activity

[PR #23744] [CLOSED] Feat: Migrate from KaTeX to MathJax for enhanced Mathematics and Chemistry rendering #42980

New Issue
Closed
opened 2026-04-25 14:43:32 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-25 14:43:32 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/open-webui/open-webui/pull/23744
Author: @jorgeventura
Created: 4/15/2026
Status: ❌ Closed

Base: dev ← Head: feat-katex2mathjax-18507

📝 Commits (10+)

📊 Changes

12 files changed (+224 additions, -111 deletions)

View changed files

📝 package-lock.json (+16 -1)
📝 package.json (+1 -1)
📝 src/app.css (+7 -11)
📝 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 (+2 -2)
📝 src/lib/utils/marked/math-extension.ts (+68 -53)
📝 vite.config.ts (+3 -0)

📄 Description

Title:

feat: Migrate from KaTeX to MathJax for enhanced Mathematics and Chemistry rendering

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.

Fixed

  • 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 Changes

  • 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 from KaTeX vs. the stable render in MathJax
Screenshot_20260414_095333-1

Contributor License Agreement

🔄 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/23744 **Author:** [@jorgeventura](https://github.com/jorgeventura) **Created:** 4/15/2026 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `feat-katex2mathjax-18507` --- ### 📝 Commits (10+) - [`fe6783c`](https://github.com/open-webui/open-webui/commit/fe6783c16699911c7be17392596d579333fb110c) Merge pull request #19030 from open-webui/dev - [`fc05e0a`](https://github.com/open-webui/open-webui/commit/fc05e0a6c5d39da60b603b4d520f800d6e36f748) Merge pull request #19405 from open-webui/dev - [`e3faec6`](https://github.com/open-webui/open-webui/commit/e3faec62c58e3a83d89aa3df539feacefa125e0c) Merge pull request #19416 from open-webui/dev - [`9899293`](https://github.com/open-webui/open-webui/commit/9899293f050ad50ae12024cbebee7e018acd851e) Merge pull request #19448 from open-webui/dev - [`140605e`](https://github.com/open-webui/open-webui/commit/140605e660b8186a7d5c79fb3be6ffb147a2f498) Merge pull request #19462 from open-webui/dev - [`6f1486f`](https://github.com/open-webui/open-webui/commit/6f1486ffd0cb288d0e21f41845361924e0d742b3) Merge pull request #19466 from open-webui/dev - [`d95f533`](https://github.com/open-webui/open-webui/commit/d95f533214e3fe5beb5e41ec1f349940bc4c7043) Merge pull request #19729 from open-webui/dev - [`a727153`](https://github.com/open-webui/open-webui/commit/a7271532f8a38da46785afcaa7e65f9a45e7d753) 0.6.43 (#20093) - [`6adde20`](https://github.com/open-webui/open-webui/commit/6adde203cd292a9e3af9c64a2ae36b603fed096a) Merge pull request #20394 from open-webui/dev - [`f9b0534`](https://github.com/open-webui/open-webui/commit/f9b0534e0c442631d1cb7205169588b9b6204179) Merge pull request #20522 from open-webui/dev ### 📊 Changes **12 files changed** (+224 additions, -111 deletions) <details> <summary>View changed files</summary> 📝 `package-lock.json` (+16 -1) 📝 `package.json` (+1 -1) 📝 `src/app.css` (+7 -11) 📝 `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` (+2 -2) 📝 `src/lib/utils/marked/math-extension.ts` (+68 -53) 📝 `vite.config.ts` (+3 -0) </details> ### 📄 Description ### Title: `feat: Migrate from KaTeX to MathJax for enhanced Mathematics and Chemistry rendering` --- ### 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. ### Fixed - **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 Changes - **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 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/80aa0e31-bf49-4343-a76e-93f9242fc755" /> ### 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>
GiteaMirror added the pull-request label 2026-04-25 14:43:32 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
confirmed
confirmed issue
core
documentation
enhancement
good first issue
help wanted
non-core
pull-request
Mirrored from GitHub Pull Request
 python
question
testing wanted
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/open-webui#42980
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?