@webc.site/math 0.1.18 → 0.1.20

package/README.md

@@ -24,8 +24,8 @@ No need to load hundreds of KB of KaTeX/MathJax and large font packages. At just
   - [2. Generation Speed (Ops/sec)](#2-generation-speed-opssec)
 - [Usage](#usage)
   - [JavaScript Examples](#javascript-examples)
-  - [Markdown Parser Plugins](#markdown-parser-plugins)
   - [CSS and Math Font Configuration](#css-and-math-font-configuration)
+  - [Markdown Parser Plugins](#markdown-parser-plugins)
 - [Features](#features)
 - [Supported Syntax List](#supported-syntax-list)
 - [Unsupported Syntax](#unsupported-syntax)
@@ -112,83 +112,62 @@ console.log(html);
 // Output: Euler's identity: <math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><msup><mi>e</mi><mrow><mi>i</mi><mi>π</mi></mrow></msup><mo>+</mo><mn>1</mn><mo>=</mo><mn>0</mn></mrow><annotation encoding="application/x-tex">e^{i\pi} + 1 = 0</annotation></semantics></math>
 ```
 
-### Markdown Parser Plugins
-
-#### 1. Marked Extension
+### CSS and Math Font Configuration
 
-Use [`@webc.site/math-marked`](https://www.npmjs.com/package/@webc.site/math-marked) to automatically parse and compile inline (`$...$`) and block (`$$...$$`) formulas:
+To ensure beautifully typeset browser-native math equations, using a math font is recommended. We recommend the **Latin Modern Math** font from the `18s` package (derived from Donald Knuth's classical Computer Modern, supporting OpenType MATH table features).
 
-```javascript
-import { marked } from "marked";
-import mathMarked from "@webc.site/math-marked";
+#### 1. Online Reference (Recommended)
 
-marked.use(mathMarked());
+Import the online font in CSS:
 
-const html = marked.parse("Euler's identity: $$e^{i\\pi} + 1 = 0$$");
+```css
+/* Import the bundle (includes Source Han Sans t, monospace c, and math font m) */
+@import url("//registry.npmmirror.com/18s/0.2.24/files/_.css");
 ```
 
-#### 2. Remark Plugin
-
-Use [`@webc.site/math-remark`](https://www.npmjs.com/package/@webc.site/math-remark) to replace `inlineMath` and `math` nodes in Unified/Remark AST with native MathML HTML:
-
-```javascript
-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";
+Or import the math font `m` only:
 
-const html = await unified()
-  .use(remarkParse)
-  .use(remarkMath)
-  .use(mathRemark)
-  .use(remarkHtml, { sanitize: false })
-  .process("Euler's identity: $$e^{i\\pi} + 1 = 0$$");
+```css
+@import url("//registry.npmmirror.com/18s/0.2.24/files/m.css");
 ```
 
-#### 3. Markdown-it Plugin
+#### 2. Configure CSS Style
 
-Use [`@webc.site/math-markdown-it`](https://www.npmjs.com/package/@webc.site/math-markdown-it) to automatically parse and render inline/block formulas in `markdown-it`:
+Set the font family for the `math` tag in your global CSS stylesheet.
 
-```javascript
-import markdownit from "markdown-it";
-import mathMarkdownIt from "@webc.site/math-markdown-it";
+##### Option A: Using Online Fonts (Recommended for best visual quality)
 
-const md = markdownit().use(mathMarkdownIt);
+For projects importing the `18s` font assets (which contains the optimized math font `m` and Source Han Sans `t`):
 
-const html = md.render("Euler's identity: $$e^{i\\pi} + 1 = 0$$");
+```css
+math {
+  /* m is the math font, t is Source Han Sans (optimized with font slicing for Chinese characters to boost loading performance), math is system math font, sans-serif is default fallback */
+  font-family: m, t, math, sans-serif;
+}
 ```
 
-### CSS and Math Font Configuration
-
-To ensure beautifully typeset browser-native math equations, using a math font is recommended. We recommend the **Latin Modern Math** font from the `18s` package (derived from Donald Knuth's classical Computer Modern, supporting OpenType MATH table features).
-
-#### 1. Online Reference (Recommended)
+##### Option B: Using System Math Fonts (Zero external font assets)
 
-Import the online font in CSS:
+Leverage system-default math fonts to minimize loading size:
 
 ```css
-/* Import the bundle (includes Source Han Sans t, monospace c, and math font m) */
-@import url("//registry.npmmirror.com/18s/0.2.24/files/_.css");
+math {
+  /* Prioritize system-built-in math fonts, fallback to standard CSS 'math' generic font family, and use sans-serif as a final fallback */
+  font-family: "STIX Two Math", "Latin Modern Math", "Cambria Math", math, sans-serif;
+}
 ```
 
-Or import the math font `m` only:
+#### 3. Integration with Build Tools
 
-```css
-@import url("//registry.npmmirror.com/18s/0.2.24/files/m.css");
-```
-
-#### 2. Local Installation
+Install the `18s` font package via npm, and import it at your project entry using build tools like Vite or Webpack:
 
 ```bash
 npm install 18s
 ```
 
-##### Import Local Font
-
-Choose one of the following methods (Note: do not mix JS and CSS imports):
+Import font styles in your project entry file:
 
-###### Method 1: Import in JS/TS Entry File
+##### Method A: Import in JS/TS Entry File
 
 ```javascript
 // Import the bundle (includes Source Han Sans t, monospace c, and math font m)
@@ -201,7 +180,7 @@ Or import math font `m` only:
 import "18s/m.css";
 ```
 
-###### Method 2: Import in CSS Stylesheet
+##### Method B: Import in CSS Stylesheet
 
 ```css
 /* Import the bundle (includes Source Han Sans t, monospace c, and math font m) */
@@ -214,30 +193,51 @@ Or import math font `m` only:
 @import "18s/m.css";
 ```
 
-#### 3. Configure CSS Style
+### Markdown Parser Plugins
 
-Set the font family for the `math` tag in your global CSS stylesheet.
+#### 1. Marked Extension
 
-##### Option A: Using Hosted/Local Fonts (Recommended for best visual quality)
+Use [`@webc.site/math-marked`](https://www.npmjs.com/package/@webc.site/math-marked) to automatically parse and compile inline (`$...$`) and block (`$$...$$`) formulas:
 
-For projects importing the `18s` font assets (which contains the optimized math font `m` and Source Han Sans `t`):
+```javascript
+import { marked } from "marked";
+import mathMarked from "@webc.site/math-marked";
 
-```css
-math {
-  /* m is the math font, t is Source Han Sans (optimized with font slicing for Chinese characters to boost loading performance), math is system math font, sans-serif is default fallback */
-  font-family: m, t, math, sans-serif;
-}
+marked.use(mathMarked());
+
+const html = marked.parse("Euler's identity: $$e^{i\\pi} + 1 = 0$$");
 ```
 
-##### Option B: Using System Math Fonts (Zero external font assets)
+#### 2. Remark Plugin
 
-Leverage system-default math fonts to minimize loading size:
+Use [`@webc.site/math-remark`](https://www.npmjs.com/package/@webc.site/math-remark) to replace `inlineMath` and `math` nodes in Unified/Remark AST with native MathML HTML:
 
-```css
-math {
-  /* Prioritize system-built-in math fonts, fallback to standard CSS 'math' generic font family */
-  font-family: "STIX Two Math", "Latin Modern Math", "Cambria Math", math;
-}
+```javascript
+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 html = await unified()
+  .use(remarkParse)
+  .use(remarkMath)
+  .use(mathRemark)
+  .use(remarkHtml, { sanitize: false })
+  .process("Euler's identity: $$e^{i\\pi} + 1 = 0$$");
+```
+
+#### 3. Markdown-it Plugin
+
+Use [`@webc.site/math-markdown-it`](https://www.npmjs.com/package/@webc.site/math-markdown-it) to automatically parse and render inline/block formulas in `markdown-it`:
+
+```javascript
+import markdownit from "markdown-it";
+import mathMarkdownIt from "@webc.site/math-markdown-it";
+
+const md = markdownit().use(mathMarkdownIt);
+
+const html = md.render("Euler's identity: $$e^{i\\pi} + 1 = 0$$");
 ```
 
 ## Features
@@ -466,8 +466,8 @@ In combination with the **Latin Modern Math** font (`m` from `18s` package), `@w
   - [2. 生成速度对比](#2-生成速度对比)
 - [使用方法](#使用方法)
   - [JavaScript 示例](#javascript-示例)
-  - [Markdown 解析器插件](#markdown-解析器插件)
   - [CSS 与数学字体配置](#css-与数学字体配置)
+  - [Markdown 解析器插件](#markdown-解析器插件)
 - [功能特性](#功能特性)
 - [支持的语法清单](#支持的语法清单)
 - [不支持的语法](#不支持的语法)
@@ -554,83 +554,62 @@ console.log(html);
 // 输出: 欧拉恒等式：<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><msup><mi>e</mi><mrow><mi>i</mi><mi>π</mi></mrow></msup><mo>+</mo><mn>1</mn><mo>=</mo><mn>0</mn></mrow><annotation encoding="application/x-tex">e^{i\pi} + 1 = 0</annotation></semantics></math>
 ```
 
-### Markdown 解析器插件
-
-#### 1. Marked 插件
+### CSS 与数学字体配置
 
-使用 [`@webc.site/math-marked`](https://www.npmjs.com/package/@webc.site/math-marked) 自动解析并编译行内（`$...$`）与块级（`$$...$$`）公式：
+为保证浏览器原生数学公式的排版，建议配置数学字体。推荐使用 `18s` 字体包的 **Latin Modern Math**（源自高德纳的 Computer Modern 字体，支持 OpenType 数学排版特性）。
 
-```javascript
-import { marked } from "marked";
-import mathMarked from "@webc.site/math-marked";
+#### 1. 在线引用
 
-marked.use(mathMarked());
+在 CSS 中通过 `@import` 引入在线字体：
 
-const html = marked.parse("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$");
+```css
+/* 引入合并后的字体 CSS（包含思源黑体 t、代码字体 c 及数学字体 m） */
+@import url("//registry.npmmirror.com/18s/0.2.24/files/_.css");
 ```
 
-#### 2. Remark 插件
-
-使用 [`@webc.site/math-remark`](https://www.npmjs.com/package/@webc.site/math-remark) 将 Unified/Remark AST 中的 `inlineMath` 与 `math` 节点替换为原生 MathML HTML：
-
-```javascript
-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";
+或者仅按需引入数学字体 `m`：
 
-const html = await unified()
-  .use(remarkParse)
-  .use(remarkMath)
-  .use(mathRemark)
-  .use(remarkHtml, { sanitize: false })
-  .process("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$");
+```css
+@import url("//registry.npmmirror.com/18s/0.2.24/files/m.css");
 ```
 
-#### 3. Markdown-it 插件
+#### 2. 配置 CSS 样式
 
-使用 [`@webc.site/math-markdown-it`](https://www.npmjs.com/package/@webc.site/math-markdown-it) 自动解析并渲染 `markdown-it` 中的行内与块级公式：
+在全局 CSS 样式表中，为 `math` 标签指定数学字体。
 
-```javascript
-import markdownit from "markdown-it";
-import mathMarkdownIt from "@webc.site/math-markdown-it";
+##### 方案 A：使用在线字体（推荐，效果最完美）
 
-const md = markdownit().use(mathMarkdownIt);
+引入 `18s` 提供的字体包（含切片优化思源黑体 `t` 与数学字体 `m`）：
 
-const html = md.render("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$");
+```css
+math {
+  /* m 为数学字体，t 为思源黑体（对中文字符进行了切片优化以提升加载性能），math 为系统数学字体，sans-serif 为系统默认无衬线字体 */
+  font-family: m, t, math, sans-serif;
+}
 ```
 
-### CSS 与数学字体配置
-
-为保证浏览器原生数学公式的排版，建议配置数学字体。推荐使用 `18s` 字体包的 **Latin Modern Math**（源自高德纳的 Computer Modern 字体，支持 OpenType 数学排版特性）。
-
-#### 1. 在线引用
+##### 方案 B：使用系统数学字体（免引入外部资源）
 
-在 CSS 中通过 `@import` 引入在线字体：
+直接使用系统内置数学字体以最小化体积：
 
 ```css
-/* 引入合并后的字体 CSS（包含思源黑体 t、代码字体 c 及数学字体 m） */
-@import url("//registry.npmmirror.com/18s/0.2.24/files/_.css");
+math {
+  /* 优先使用各平台内置的数学字体，其次降级到 CSS 标准 math 泛型，最后以系统默认无衬线字体作为后备 */
+  font-family: "STIX Two Math", "Latin Modern Math", "Cambria Math", math, sans-serif;
+}
 ```
 
-或者仅按需引入数学字体 `m`：
+#### 3. 配合构建工具引用
 
-```css
-@import url("//registry.npmmirror.com/18s/0.2.24/files/m.css");
-```
-
-#### 2. 本地安装字体包
+通过 npm 安装 `18s` 字体包，配合 Vite、Webpack 等构建工具在项目入口中引入：
 
 ```bash
 npm install 18s
 ```
 
-##### 引入本地字体
-
-选择以下一种方式引入字体映射（注意：请勿混用 JS 与 CSS 引入）：
+在项目入口文件中引入字体样式：
 
-###### 方式 1：在项目入口 JS/TS 文件中引入
+##### 方式 A：在 JS/TS 入口中引入
 
 ```javascript
 // 引入合并后的字体 CSS（包含思源黑体 t、代码字体 c 及数学字体 m）
@@ -643,7 +622,7 @@ import "18s/_.css";
 import "18s/m.css";
 ```
 
-###### 方式 2：在项目入口 CSS 文件中引入
+##### 方式 B：在 CSS 入口中引入
 
 ```css
 /* 引入合并后的字体 CSS（包含思源黑体 t、代码字体 c 及数学字体 m） */
@@ -656,30 +635,51 @@ import "18s/m.css";
 @import "18s/m.css";
 ```
 
-#### 3. 配置 CSS 样式
+### Markdown 解析器插件
 
-在全局 CSS 样式表中，为 `math` 标签指定数学字体。
+#### 1. Marked 插件
 
-##### 方案 A：使用托管/本地字体（推荐，效果最完美）
+使用 [`@webc.site/math-marked`](https://www.npmjs.com/package/@webc.site/math-marked) 自动解析并编译行内（`$...$`）与块级（`$$...$$`）公式：
 
-引入 `18s` 提供的字体包（含切片优化思源黑体 `t` 与数学字体 `m`）：
+```javascript
+import { marked } from "marked";
+import mathMarked from "@webc.site/math-marked";
 
-```css
-math {
-  /* m 为数学字体，t 为思源黑体（对中文字符进行了切片优化以提升加载性能），math 为系统数学字体，sans-serif 为系统默认无衬线字体 */
-  font-family: m, t, math, sans-serif;
-}
+marked.use(mathMarked());
+
+const html = marked.parse("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$");
 ```
 
-##### 方案 B：使用系统数学字体（免引入外部资源）
+#### 2. Remark 插件
 
-直接使用系统内置数学字体以最小化体积：
+使用 [`@webc.site/math-remark`](https://www.npmjs.com/package/@webc.site/math-remark) 将 Unified/Remark AST 中的 `inlineMath` 与 `math` 节点替换为原生 MathML HTML：
 
-```css
-math {
-  /* 优先使用各平台内置的数学字体，最后降级到 CSS 标准 math 泛型字体 */
-  font-family: "STIX Two Math", "Latin Modern Math", "Cambria Math", math;
-}
+```javascript
+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 html = await unified()
+  .use(remarkParse)
+  .use(remarkMath)
+  .use(mathRemark)
+  .use(remarkHtml, { sanitize: false })
+  .process("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$");
+```
+
+#### 3. Markdown-it 插件
+
+使用 [`@webc.site/math-markdown-it`](https://www.npmjs.com/package/@webc.site/math-markdown-it) 自动解析并渲染 `markdown-it` 中的行内与块级公式：
+
+```javascript
+import markdownit from "markdown-it";
+import mathMarkdownIt from "@webc.site/math-markdown-it";
+
+const md = markdownit().use(mathMarkdownIt);
+
+const html = md.render("欧拉恒等式：$$e^{i\\pi} + 1 = 0$$");
 ```
 
 ## 功能特性

package/package.json

@@ -1 +1 @@
-{"name":"@webc.site/math","version":"0.1.18","description":"The world's smallest and fastest web Markdown formula renderer / 全球最小最快的网页Markdown公式渲染器","keywords":["markdown","math","mathml","render","tex"],"homepage":"https://math.webc.site","license":"MulanPSL-2.0","author":"i18n.site@gmail.com","repository":{"type":"git","url":"git+https://github.com/webc-site/math.git"},"type":"module","exports":{".":{"types":"./mathml.d.ts","default":"./mathml.js"},"./md.js":{"types":"./md.d.ts","default":"./md.js"},"./*":"./*"},"dependencies":{}}
+{"name":"@webc.site/math","version":"0.1.20","description":"The world's smallest and fastest web Markdown formula renderer / 全球最小最快的网页Markdown公式渲染器","keywords":["markdown","math","mathml","render","tex"],"homepage":"https://math.webc.site","license":"MulanPSL-2.0","author":"i18n.site@gmail.com","repository":{"type":"git","url":"git+https://github.com/webc-site/math.git"},"type":"module","exports":{".":{"types":"./mathml.d.ts","default":"./mathml.js"},"./md.js":{"types":"./md.d.ts","default":"./md.js"},"./*":"./*"},"dependencies":{}}