@webc.site/math
v0.1.26
Published
The world's smallest and fastest web Markdown formula renderer / 全球最小最快的网页Markdown公式渲染器
Maintainers
i18n-nowReadme
@webc.site/math : The world's smallest and fastest web Markdown formula renderer
1. Features
This project compiles LaTeX math formulas into browser-native MathML Core markup. Through compile-time conversion, it bypasses client-side layout engines to achieve zero-overhead formula rendering.
Key Features:
- High Performance: Compiles TeX formulas directly to native MathML. Processing speed exceeds 300,000 operations per second, 3 times faster than KaTeX and 40 times faster than MathJax.
- Lightweight: Core package size is 7.69 KB (3.56 KB gzipped) with zero external dependencies.
- Zero Runtime Overhead: Relies entirely on the browser's native engine for layout, eliminating client-side JavaScript formatting libraries.
- Robust Fault Tolerance: Catches syntax errors (such as unclosed braces) and reverts to raw TeX string output to prevent application crashes.
- High Compatibility: Generates standard MathML tags suitable for Server-Side Rendering (SSR), Static Site Generation (SSG), and Client-Side Rendering (CSR).
2. Usage
Compilation Examples
Render TeX Formulas Directly
import mathml from "@webc.site/math";
// Second parameter set to true renders block style
const html = mathml("e^{i\\pi} + 1 = 0", true);Replace Formulas in Markdown Text
import mdMath from "@webc.site/math/md.js";
import compile from "@webc.site/math";
const html = mdMath("Euler's identity: $$e^{i\\pi} + 1 = 0$$", compile);Font and CSS Configuration
Configure math fonts to ensure proper layout alignment. Latin Modern Math font from the 18s package is recommended.
CSS Font Styling
math {
font-family: m, t, math, sans-serif;
}3. Plugins
This project provides extension plugins for mainstream Markdown parsers to render TeX formulas directly to MathML markup during compilation/building.
3.1 markdown-it
Installation:
npm install @webc.site/math-markdown-itUsage:
import markdownit from "markdown-it";
import mathMarkdownIt from "@webc.site/math-markdown-it";
const md = markdownit().use(mathMarkdownIt);
const html = md.render("Inline math: $E = mc^2$ and block math: \n$$\n\\frac{a}{b}\n$$");
console.log(html);3.2 marked
Installation:
npm install @webc.site/math-markedUsage:
import { marked } from "marked";
import mathMarked from "@webc.site/math-marked";
marked.use(mathMarked());
const html = marked.parse("Inline math: $E = mc^2$ and block math: \n$$\n\\frac{a}{b}\n$$");
console.log(html);3.3 remark
Installation:
npm install @webc.site/math-remarkUsage:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkMath from "remark-math";
import mathRemark from "@webc.site/math-remark";
import remarkHtml from "remark-html";
const processor = unified()
.use(remarkParse)
.use(remarkMath)
.use(mathRemark)
.use(remarkHtml, { sanitize: false });
const html = await processor.process(
"Inline math: $E = mc^2$ and block math: \n$$\n\\frac{a}{b}\n$$",
);
console.log(String(html));4. Design
The compiler extracts TeX formulas from input Markdown text, tokenizes and parses them, and translates the AST to semantic MathML markup.
5. Tech Stack
- Build & Test Environment: Bun, Node.js
- Linter & Formatter: oxlint, oxfmt
- Build Tool: Vite, Rolldown, Lightning CSS
6. Code Structure
.
├── demo/ # Interactive demo page
├── extract/ # Test cases extraction scripts
├── lib/ # Compiled distribution files
│ ├── mathml.js # Core compiler (minified)
│ └── md.js # Markdown math formula parser (minified)
├── src/ # Source code
│ ├── const/ # Tokens, AST types, symbols, and functions constants
│ ├── lex.js # LaTeX lexer
│ ├── parse.js # LaTeX parser (AST builder)
│ ├── mathml.js # Core TeX-to-MathML compiler
│ └── md.js # Markdown parser entry
├── sh/ # Scripts
└── test.sh # Quality verification and test runner7. Historical Background
The W3C published the MathML 1.0 specification in 1998 to standardize mathematical notation on the web. However, the complexity of the specification placed a maintenance burden on browser layout engines.
In 2013, the Chromium team removed the unfinished MathML rendering implementation from the Blink engine due to maintenance costs and security vulnerabilities. Web developers subsequently relied on client-side JavaScript libraries (such as MathJax and KaTeX) to simulate formula layout. These libraries increased bundle sizes and consumed client-side CPU resources, impacting page load times and rendering performance.
To resolve this issue, organizations like Igalia and Mozilla refactored the specification into the MathML Core standard, focusing on essential, implementable parts backed by Web Platform Tests.
In January 2023, Chrome 109 reintroduced support for the MathML Core specification. With Blink, Gecko, and WebKit all natively supporting this subset, web browsers achieved consistent native MathML rendering. This project compiles TeX directly to native MathML markup at compile time, eliminating client-side layout engines and avoiding client-side rendering overhead.
@webc.site/math : 全球最小最快的网页 Markdown 公式渲染器
1. 功能介绍
本项目将 LaTeX 数学公式编译为浏览器原生支持的 MathML Core 标记。通过编译期转换，无需客户端排版引擎，实现零运行时开销的公式渲染。
主要特性：
- 高性能：TeX 公式直接转换为原生 MathML 标签。处理速度达每秒 300,000 次以上，为 KaTeX 的 3 倍以上，MathJax 的 40 倍以上。
- 轻量化：核心包体积 7.69 KB（Gzip 压缩后 3.56 KB），无外部依赖。
- 零运行开销：完全依赖浏览器原生引擎排版与渲染，无需加载客户端 JavaScript 排版库。
- 高容错性：自动捕获语法错误（例如未闭合括号），降级输出原始 TeX 字符串，保证应用运行稳定。
- 强兼容性：生成的 MathML 标签符合标准，适配服务端渲染（SSR）、静态网站生成（SSG）和客户端渲染（CSR）。
2. 使用演示
编译示例
直接渲染 TeX 公式
import mathml from "@webc.site/math";
// 第二参数为 true 表示渲染为块级公式
const html = mathml("e^{i\\pi} + 1 = 0", true);替换 Markdown 文本中的公式
import mdMath from "@webc.site/math/md.js";
import compile from "@webc.site/math";
const html = mdMath("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$", compile);字体与 CSS 配置
配置数学字体以确保排版对齐。推荐使用 18s 字体包中的 Latin Modern Math 字体。
CSS 样式配置
math {
font-family: m, t, math, sans-serif;
}3. 插件使用
本项目为主流 Markdown 解析器提供了扩展插件，在编译/构建时直接将 TeX 公式渲染为 MathML 标签。
3.1 markdown-it
安装：
npm install @webc.site/math-markdown-it使用示例：
import markdownit from "markdown-it";
import mathMarkdownIt from "@webc.site/math-markdown-it";
const md = markdownit().use(mathMarkdownIt);
const html = md.render("行内公式: $E = mc^2$ 和 块级公式: \n$$\n\\frac{a}{b}\n$$");
console.log(html);3.2 marked
安装：
npm install @webc.site/math-marked使用示例：
import { marked } from "marked";
import mathMarked from "@webc.site/math-marked";
marked.use(mathMarked());
const html = marked.parse("行内公式: $E = mc^2$ 和 块级公式: \n$$\n\\frac{a}{b}\n$$");
console.log(html);3.3 remark
安装：
npm install @webc.site/math-remark使用示例：
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkMath from "remark-math";
import mathRemark from "@webc.site/math-remark";
import remarkHtml from "remark-html";
const processor = unified()
.use(remarkParse)
.use(remarkMath)
.use(mathRemark)
.use(remarkHtml, { sanitize: false });
const html = await processor.process("行内公式: $E = mc^2$ 和 块级公式: \n$$\n\\frac{a}{b}\n$$");
console.log(String(html));4. 设计思路
编译器从输入的 Markdown 文本中提取 TeX 公式，依次通过扫描、词法分析、语法分析，最终生成对应的语义化 MathML 标记。
5. 技术栈
- 运行环境：Bun, Node.js
- 语法检查与格式化：oxlint, oxfmt
- 构建工具：Vite, Rolldown, Lightning CSS
6. 代码结构
.
├── demo/ # 演示页面
├── extract/ # 测试用例提取脚本
├── lib/ # 编译产物目录
│ ├── mathml.js # 核心编译器（压缩版）
│ └── md.js # Markdown 公式解析器（压缩版）
├── src/ # 源代码
│ ├── const/ # Token、AST 节点、符号和函数常量定义
│ ├── lex.js # LaTeX 词法分析器
│ ├── parse.js # LaTeX 语法分析器
│ ├── mathml.js # TeX 至 MathML 核心编译器
│ └── md.js # Markdown 公式解析入口
├── sh/ # 脚本目录
└── test.sh # 代码规范与测试运行脚本7. 历史故事
1998 年，W3C 发布 MathML 1.0 规范，旨在提供万维网数学公式的标准排版方案。由于早期规范复杂，给浏览器排版引擎带来维护负担。
2013 年，Chromium 团队因维护成本与安全漏洞考量，移除了 Blink 引擎中的 MathML 渲染代码。网页公式排版转为依赖第三方 JavaScript 库（如 MathJax、KaTeX）模拟公式布局。这增加了网页资源体积，并消耗客户端 CPU 资源，影响页面加载与渲染速度。
为了解决该困境，Igalia、Mozilla 等团队推动了规范的重构，形成聚焦核心、易于实现的 MathML Core 标准，并进行了 Web 平台测试。
2023 年 1 月，Chrome 109 重新支持 MathML Core 标准，Blink、Gecko 和 WebKit 三大主流浏览器引擎实现原生 MathML 渲染支持。本项目在此背景下开发，将 TeX 在构建期或服务端直接编译为原生 MathML 标记，消除客户端排版计算开销。