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.3k Packages Projects Releases 126 Wiki Activity

[PR #23791] [CLOSED] feat: replace katex engine to mathjax #27368

New Issue
Closed
opened 2026-04-20 07:02:10 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-20 07:02:10 -05:00
Owner
Copy Link

📋 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)

  • 5fc8696 Feat: Integrate MathJax support for math rendering
  • b7366fe Refactor math delimiter regex for block content
  • d6edf06 Matrices are working
  • bb95afc Needs remove $ in excess
  • 40f38ab The $ excess fixed.
  • 369c55c feat(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 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).
    • 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
Screenshot_20260414_095333-1
  • Chemical formula
Screenshot_20260415_080140

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/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>
GiteaMirror added the pull-request label 2026-04-20 07:02:10 -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#27368
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?