Skip to content

Commit e87a545

Browse files
x-at-01x-at-01
committed
v0.1.26
1 parent 299e13a commit e87a545

7 files changed

Lines changed: 70 additions & 117 deletions

File tree

‎README.md‎

Lines changed: 32 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -203,37 +203,29 @@ In January 2023, Chrome 109 reintroduced support for the MathML Core specificati
203203
- [@webc.site/math : 全球最小最快的网页 Markdown 公式渲染器](#webcsitemath-全球最小最快的网页-markdown-公式渲染器)
204204
- [1. 功能介绍](#1-功能介绍)
205205
- [2. 使用演示](#2-使用演示)
206-
- [编译示例](#编译示例)
207-
- [直接渲染 TeX 公式](#直接渲染-tex-公式)
208-
- [替换 Markdown 文本中的公式](#替换-markdown-文本中的公式)
206+
- [直接渲染 TeX 公式](#直接渲染-tex-公式)
207+
- [替换 Markdown 文本中的公式](#替换-markdown-文本中的公式)
209208
- [字体与 CSS 配置](#字体与-css-配置)
210-
- [CSS 样式配置](#css-样式配置)
211-
- [3. 插件使用](#3-插件使用)
212-
- [3.1 markdown-it](#31-markdown-it)
213-
- [3.2 marked](#32-marked)
214-
- [3.3 remark](#33-remark)
215-
- [4. 设计思路](#4-设计思路)
216-
- [5. 技术栈](#5-技术栈)
217-
- [6. 代码结构](#6-代码结构)
218-
- [7. 历史故事](#7-历史故事)
209+
- [3. 设计思路](#3-设计思路)
210+
- [4. 技术栈](#4-技术栈)
211+
- [5. 代码结构](#5-代码结构)
212+
- [6. 历史故事](#6-历史故事)
219213

220214
## 1. 功能介绍
221215

222216
本项目将 LaTeX 数学公式编译为浏览器原生支持的 MathML Core 标记。通过编译期转换，无需客户端排版引擎，实现零运行时开销的公式渲染。
223217

224-
主要特性：
218+
核心特性：
225219

226-
- **高性能**：TeX 公式直接转换为原生 MathML 标签。处理速度达每秒 300,000 次以上，为 KaTeX 的 3 倍以上，MathJax 的 40 倍以上。
227-
- **轻量化**：核心包体积 7.69 KB（Gzip 压缩后 3.56 KB），无外部依赖。
228-
- **零运行开销**：完全依赖浏览器原生引擎排版与渲染，无需加载客户端 JavaScript 排版库。
229-
- **高容错性**：自动捕获语法错误（例如未闭合括号），降级输出原始 TeX 字符串，保证应用运行稳定。
230-
- **强兼容性**：生成的 MathML 标签符合标准，适配服务端渲染（SSR）、静态网站生成（SSG）和客户端渲染（CSR）。
220+
- **高性能**：TeX 公式直接转换为原生 MathML 标签，处理速度达每秒 300,000 次以上
221+
- **轻量化**：核心包体积 7.69 KB（Gzip 压缩后 3.56 KB），无外部依赖
222+
- **零运行开销**：完全依赖浏览器原生引擎排版与渲染
223+
- **高容错性**：自动捕获语法错误，降级输出原始 TeX 字符串
224+
- **强兼容性**：生成标准 MathML 标签，适配 SSR、SSG 和 CSR
231225

232226
## 2. 使用演示
233227

234-
### 编译示例
235-
236-
#### 直接渲染 TeX 公式
228+
### 直接渲染 TeX 公式
237229

238230
```javascript
239231
import mathml from "@webc.site/math";
@@ -242,7 +234,7 @@ import mathml from "@webc.site/math";
242234
const html = mathml("e^{i\\pi} + 1 = 0", true);
243235
```
244236

245-
#### 替换 Markdown 文本中的公式
237+
### 替换 Markdown 文本中的公式
246238

247239
```javascript
248240
import mdMath from "@webc.site/math/md.js";
@@ -253,94 +245,21 @@ const html = mdMath("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$", compile);
253245

254246
### 字体与 CSS 配置
255247

256-
配置数学字体以确保排版对齐。推荐使用 `18s` 字体包中的 Latin Modern Math 字体。
257-
258-
#### CSS 样式配置
248+
配置数学字体确保排版对齐：
259249

260250
```css
261251
math {
262252
font-family: m, t, math, sans-serif;
263253
}
264254
```
265255

266-
## 3. 插件使用
267-
268-
本项目为主流 Markdown 解析器提供了扩展插件，在编译/构建时直接将 TeX 公式渲染为 MathML 标签。
269-
270-
### 3.1 markdown-it
271-
272-
安装：
273-
274-
```bash
275-
npm install @webc.site/math-markdown-it
276-
```
277-
278-
使用示例：
279-
280-
```javascript
281-
import markdownit from "markdown-it";
282-
import mathMarkdownIt from "@webc.site/math-markdown-it";
283-
284-
const md = markdownit().use(mathMarkdownIt);
285-
286-
const html = md.render("行内公式: $E = mc^2$ 和 块级公式: \n$$\n\\frac{a}{b}\n$$");
287-
console.log(html);
288-
```
289-
290-
### 3.2 marked
291-
292-
安装：
293-
294-
```bash
295-
npm install @webc.site/math-marked
296-
```
297-
298-
使用示例：
299-
300-
```javascript
301-
import { marked } from "marked";
302-
import mathMarked from "@webc.site/math-marked";
303-
304-
marked.use(mathMarked());
305-
306-
const html = marked.parse("行内公式: $E = mc^2$ 和 块级公式: \n$$\n\\frac{a}{b}\n$$");
307-
console.log(html);
308-
```
309-
310-
### 3.3 remark
311-
312-
安装：
313-
314-
```bash
315-
npm install @webc.site/math-remark
316-
```
256+
## 3. 设计思路
317257

318-
使用示例：
319-
320-
```javascript
321-
import { unified } from "unified";
322-
import remarkParse from "remark-parse";
323-
import remarkMath from "remark-math";
324-
import mathRemark from "@webc.site/math-remark";
325-
import remarkHtml from "remark-html";
326-
327-
const processor = unified()
328-
.use(remarkParse)
329-
.use(remarkMath)
330-
.use(mathRemark)
331-
.use(remarkHtml, { sanitize: false });
332-
333-
const html = await processor.process("行内公式: $E = mc^2$ 和 块级公式: \n$$\n\\frac{a}{b}\n$$");
334-
console.log(String(html));
335-
```
336-
337-
## 4. 设计思路
338-
339-
编译器从输入的 Markdown 文本中提取 TeX 公式，依次通过扫描、词法分析、语法分析，最终生成对应的语义化 MathML 标记。
258+
编译器从输入文本中提取 TeX 公式，依次通过扫描、词法分析、语法分析，最终生成语义化 MathML 标记。
340259

341260
```mermaid
342261
graph TD
343-
Input[输入 Markdown] --> Scanner[扫描器: 定界符定位]
262+
Input[输入文本] --> Scanner[扫描器: 定界符定位]
344263
Scanner -->|普通文本| Buffer[输出缓冲区]
345264
Scanner -->|TeX 公式| Lexer[词法分析: 生成 Token]
346265
Lexer --> Parser[语法分析: 生成 AST]
@@ -351,37 +270,35 @@ graph TD
351270
MathML --> Output
352271
```
353272

354-
## 5. 技术栈
273+
## 4. 技术栈
355274

356-
- **运行环境**：Bun, Node.js
357-
- **语法检查与格式化**：oxlint, oxfmt
358-
- **构建工具**：Vite, Rolldown, Lightning CSS
275+
- **运行环境**：Node.js, Bun
276+
- **构建工具**：Rolldown, Vite
277+
- **样式处理**：Lightning CSS
278+
- **代码质量**：oxlint, oxfmt
359279

360-
## 6. 代码结构
280+
## 5. 代码结构
361281

362282
```
363283
.
364-
├── demo/ # 演示页面
365-
├── extract/ # 测试用例提取脚本
366284
├── lib/ # 编译产物目录
367-
│ ├── mathml.js # 核心编译器（压缩版）
368-
│ └── md.js # Markdown 公式解析器（压缩版）
285+
│ ├── mathml.js # 核心编译器
286+
│ └── md.js # Markdown 公式解析器
369287
├── src/ # 源代码
370288
│ ├── const/ # Token、AST 节点、符号和函数常量定义
371289
│ ├── lex.js # LaTeX 词法分析器
372290
│ ├── parse.js # LaTeX 语法分析器
373291
│ ├── mathml.js # TeX 至 MathML 核心编译器
374292
│ └── md.js # Markdown 公式解析入口
375-
├── sh/ # 脚本目录
376-
└── test.sh # 代码规范与测试运行脚本
293+
├── demo/ # 演示页面
294+
├── extract/ # 测试用例提取脚本
295+
└── sh/ # 构建脚本
377296
```
378297

379-
## 7. 历史故事
298+
## 6. 历史故事
380299

381300
1998 年，W3C 发布 MathML 1.0 规范，旨在提供万维网数学公式的标准排版方案。由于早期规范复杂，给浏览器排版引擎带来维护负担。
382301

383-
2013 年，Chromium 团队因维护成本与安全漏洞考量，移除了 Blink 引擎中的 MathML 渲染代码。网页公式排版转为依赖第三方 JavaScript 库（如 MathJax、KaTeX）模拟公式布局。这增加了网页资源体积，并消耗客户端 CPU 资源，影响页面加载与渲染速度。
384-
385-
为了解决该困境，Igalia、Mozilla 等团队推动了规范的重构，形成聚焦核心、易于实现的 MathML Core 标准，并进行了 Web 平台测试。
302+
2013 年，Chromium 团队因维护成本与安全漏洞考量，移除了 Blink 引擎中的 MathML 渲染代码。网页公式排版转为依赖第三方 JavaScript 库（如 MathJax、KaTeX）模拟公式布局。
386303

387-
2023 年 1 月，Chrome 109 重新支持 MathML Core 标准，Blink、Gecko 和 WebKit 三大主流浏览器引擎实现原生 MathML 渲染支持。本项目在此背景下开发，将 TeX 在构建期或服务端直接编译为原生 MathML 标记，消除客户端排版计算开销。
304+
2023 年 1 月，Chrome 109 重新支持 MathML Core 标准，Blink、Gecko 和 WebKit 三大主流浏览器引擎实现原生 MathML 渲染支持。本项目在此背景下开发，将 TeX 在构建期或服务端直接编译为原生 MathML 标记。

‎bun.lock‎

Lines changed: 5 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist.js‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,17 @@ import { readFileSync, writeFileSync } from "node:fs";
33
import { join } from "node:path";
44
import minify from "./minify.js";
55
import ROOT_DIR from "./sh/ROOT.js";
6+
import renderMdt from "@1-/mdt/_.js";
67
import { simpleGit } from "simple-git";
78

89
const main = async () => {
910
await minify(ROOT_DIR);
1011

12+
const mdt_path = join(ROOT_DIR, "README.mdt"),
13+
md_content = await renderMdt(mdt_path, ROOT_DIR);
14+
writeFileSync(join(ROOT_DIR, "README.md"), md_content, "utf8");
15+
console.log("README.md rendered from README.mdt");
16+
1117
const pkg_path = join(ROOT_DIR, "package.json"),
1218
pkg = JSON.parse(readFileSync(pkg_path, "utf8")),
1319
current_version = pkg.version,
@@ -25,7 +31,7 @@ const main = async () => {
2531
current_branch = status.current;
2632
console.log("Current branch: " + current_branch);
2733

28-
await git.add("-A");
34+
await git.add("-u");
2935
await git.commit("v" + next_version);
3036

3137
if (current_branch !== "main") {

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@webc.site/math",
3-
"version": "0.1.25",
3+
"version": "0.1.26",
44
"description": "The world's smallest and fastest web Markdown formula renderer / 全球最小最快的网页Markdown公式渲染器",
55
"keywords": [
66
"markdown",
@@ -39,6 +39,7 @@
3939
"@1-/findgit": "^0.1.2",
4040
"@1-/mdcheck": "^0.1.9",
4141
"@1-/mdimg2cdn": "^0.1.1",
42+
"@1-/mdt": "^0.1.9",
4243
"@3-/log": "^0.1.9",
4344
"@3-/read": "^0.1.4",
4445
"@3-/stylfmt": "^0.1.7",

‎plugin/markdown-it/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66

77
# @webc.site/math-markdown-it
88

9+
- [@webc.site/math-markdown-it](#webcsitemath-markdown-it)
10+
- [Installation](#installation)
11+
- [Usage](#usage)
12+
913
Markdown-it plugin for `@webc.site/math`. Renders Markdown math formulas (LaTeX / TeX) directly to MathML at compile time, featuring extremely small size and fast speed.
1014

1115
## Installation
@@ -32,6 +36,10 @@ console.log(html);
3236

3337
# @webc.site/math-markdown-it
3438

39+
- [@webc.site/math-markdown-it](#webcsitemath-markdown-it)
40+
- [安装](#安装)
41+
- [使用方法](#使用方法)
42+
3543
`@webc.site/math` 的 Markdown-it 扩展插件。在编译时直接将 Markdown 数学公式 (LaTeX / TeX) 渲染为 MathML，具有极小的体积和极快的运行速度。
3644

3745
## 安装

‎plugin/marked/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66

77
# @webc.site/math-marked
88

9+
- [@webc.site/math-marked](#webcsitemath-marked)
10+
- [Installation](#installation)
11+
- [Usage](#usage)
12+
913
Marked extension for `@webc.site/math`. Renders Markdown math formulas (LaTeX / TeX) directly to MathML at compile time, featuring extremely small size and fast speed.
1014

1115
## Installation
@@ -32,6 +36,10 @@ console.log(html);
3236

3337
# @webc.site/math-marked
3438

39+
- [@webc.site/math-marked](#webcsitemath-marked)
40+
- [安装](#安装)
41+
- [使用方法](#使用方法)
42+
3543
`@webc.site/math` 的 Marked 扩展插件。在编译时直接将 Markdown 数学公式 (LaTeX / TeX) 渲染为 MathML，具有极小的体积和极快的运行速度。
3644

3745
## 安装

‎plugin/remark/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66

77
# @webc.site/math-remark
88

9+
- [@webc.site/math-remark](#webcsitemath-remark)
10+
- [Installation](#installation)
11+
- [Usage](#usage)
12+
913
Remark plugin for `@webc.site/math`. Renders Markdown math formulas (LaTeX / TeX) directly to MathML at compile time, featuring extremely small size and fast speed.
1014

1115
## Installation
@@ -41,6 +45,10 @@ console.log(String(html));
4145

4246
# @webc.site/math-remark
4347

48+
- [@webc.site/math-remark](#webcsitemath-remark)
49+
- [安装](#安装)
50+
- [使用方法](#使用方法)
51+
4452
`@webc.site/math` 的 Remark 扩展插件。在编译时直接将 Markdown 数学公式 (LaTeX / TeX) 渲染为 MathML，具有极小的体积和极快的运行速度。
4553

4654
## 安装

0 commit comments

Comments
 (0)