Skip to content

Commit 178f3d1

Browse files
Mister-HopeMister-Hope
committed
feat(katex)!: rebuild mhchem support
1 parent f6f8d6a commit 178f3d1

File tree

14 files changed

+76
-113
lines changed

14 files changed

+76
-113
lines changed

‎docs/src/katex.md

+19-31
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: "@mdit/plugin-katex"
33
icon: square-root-variable
44
---
55

6-
Plugins to render math expressions with KaTeX, you should install `katex` as peer dependency.
6+
Plugins to render math expressions with KaTeX.
77

88
::: note
99

@@ -41,7 +41,7 @@ mdIt.render("$E=mc^2$");
4141

4242
:::
4343

44-
We also have a package called `@mdit/plugin-katex-slim` which `katex` is an optional dep.
44+
We also have a package called `@mdit/plugin-katex-slim` which `katex` is an optional peer.
4545

4646
## Syntax
4747

@@ -80,33 +80,21 @@ $$
8080

8181
:::
8282

83-
## Options
83+
## mhchem extension
84+
85+
If you want to load the `mhchem` extension, you should import `loadMhchem` from `@mdit/plugin-katex`:
8486

8587
```ts
86-
interface KatexCatcodes {
87-
[key: string]: number;
88-
}
88+
import { loadMhchem } from "@mdit/plugin-katex";
8989

90-
interface KatexLexerInterFace {
91-
input: string;
92-
tokenRegex: RegExp;
93-
settings: Required<KatexOptions>;
94-
catcodes: KatexCatcodes;
95-
}
90+
await loadMhchem();
91+
```
9692

97-
interface KatexSourceLocation {
98-
start: number;
99-
end: number;
100-
lexer: KatexLexerInterFace;
101-
}
93+
Since it's async, you should call it in prepare stage as markdown-it rendering is sync.
10294

103-
interface KatexToken {
104-
text: string;
105-
loc: KatexSourceLocation;
106-
noexpand: boolean | undefined;
107-
treatAsRelax: boolean | undefined;
108-
}
95+
## Options
10996

97+
```ts
11098
type KatexLogger<MarkdownItEnv = unknown> = (
11199
errorCode:
112100
| "unknownSymbol"
@@ -116,9 +104,11 @@ type KatexLogger<MarkdownItEnv = unknown> = (
116104
| "htmlExtension"
117105
| "newLineInDisplayMode",
118106
errorMsg: string,
119-
token: KatexToken,
107+
token: Token,
120108
env: MarkdownItEnv,
121-
) => "error" | "warn" | "ignore" | void;
109+
) => "error" | "warn" | "ignore" | boolean | undefined | void;
110+
111+
type TeXTransformer = (content: string, displayMode: boolean) => string;
122112

123113
interface MarkdownItKatexOptions<MarkdownItEnv = unknown> extends KatexOptions {
124114
/**
@@ -138,16 +128,14 @@ interface MarkdownItKatexOptions<MarkdownItEnv = unknown> extends KatexOptions {
138128
mathFence?: boolean;
139129

140130
/**
141-
* Whether enable mhchem extension
142-
*
143-
* @default false
131+
* Error logger
144132
*/
145-
mhchem?: boolean;
133+
logger?: KatexLogger<MarkdownItEnv>;
146134

147135
/**
148-
* Error logger
136+
* transformer on output content
149137
*/
150-
logger?: KatexLogger<MarkdownItEnv>;
138+
transformer?: TeXTransformer;
151139
}
152140
```
153141

‎docs/src/mathjax.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: "@mdit/plugin-mathjax"
33
icon: square-root-variable
44
---
55

6-
Plugins to render math expressions with Mathjax, you should install `mathjax-full` as peer dependency.
6+
Plugins to render math expressions with Mathjax.
77

88
::: note
99

@@ -105,7 +105,7 @@ The instance holds render content of each calls, so you should:
105105
- Call `mathjaxInstance.outputStyle()` after all rendering is done, to get final CSS content.
106106
- Call `mathjaxInstance.clearStyle()` to clear existing style cache if necessary.
107107

108-
We also have a package called `@mdit/plugin-mathjax-slim` which `mathjax-full` is an optional dep.
108+
We also have a package called `@mdit/plugin-mathjax-slim` which `mathjax-full` is an optional peer dep.
109109

110110
## Syntax
111111

‎docs/src/zh/katex.md

+17-31
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: "@mdit/plugin-katex"
33
icon: square-root-variable
44
---
55

6-
使用 KaTeX 呈现数学表达式的插件，你应该将 `katex` 安装为 peer 依赖。
6+
使用 KaTeX 呈现数学表达式的插件。
77

88
::: note
99

@@ -41,7 +41,7 @@ mdIt.render("$E=mc^2$");
4141

4242
:::
4343

44-
我们也有一个 `@mdit/plugin-katex-slim` 包，其中 `katex` 是可选依赖。
44+
我们也有一个 `@mdit/plugin-katex-slim` 包，其中 `katex` 是可选对等依赖。
4545

4646
## 格式
4747

@@ -80,33 +80,21 @@ $$
8080

8181
:::
8282

83-
## 选项
83+
## mhchem extension
84+
85+
如果你想加载 `mhchem` 扩展，你应该从 `@mdit/plugin-katex` 中导入 `loadMhchem`:
8486

8587
```ts
86-
interface KatexCatcodes {
87-
[key: string]: number;
88-
}
88+
import { loadMhchem } from "@mdit/plugin-katex";
8989

90-
interface KatexLexerInterFace {
91-
input: string;
92-
tokenRegex: RegExp;
93-
settings: Required<KatexOptions>;
94-
catcodes: KatexCatcodes;
95-
}
90+
await loadMhchem();
91+
```
9692

97-
interface KatexSourceLocation {
98-
start: number;
99-
end: number;
100-
lexer: KatexLexerInterFace;
101-
}
93+
因为它是异步的，你应该在准备阶段调用它，因为 markdown-it 渲染是同步的。
10294

103-
interface KatexToken {
104-
text: string;
105-
loc: KatexSourceLocation;
106-
noexpand: boolean | undefined;
107-
treatAsRelax: boolean | undefined;
108-
}
95+
## 选项
10996

97+
```ts
11098
type KatexLogger<MarkdownItEnv = unknown> = (
11199
errorCode:
112100
| "unknownSymbol"
@@ -116,9 +104,9 @@ type KatexLogger<MarkdownItEnv = unknown> = (
116104
| "htmlExtension"
117105
| "newLineInDisplayMode",
118106
errorMsg: string,
119-
token: KatexToken,
107+
token: Token,
120108
env: MarkdownItEnv,
121-
) => "error" | "warn" | "ignore" | void;
109+
) => "error" | "warn" | "ignore" | boolean | undefined | void;
122110

123111
interface MarkdownItKatexOptions<MarkdownItEnv = unknown> extends KatexOptions {
124112
/**
@@ -138,16 +126,14 @@ interface MarkdownItKatexOptions<MarkdownItEnv = unknown> extends KatexOptions {
138126
mathFence?: boolean;
139127

140128
/**
141-
* 是否启用 mhchem 扩展
142-
*
143-
* @default false
129+
* 错误日志记录器
144130
*/
145-
mhchem?: boolean;
131+
logger?: KatexLogger<MarkdownItEnv>;
146132

147133
/**
148-
* 错误日志记录器
134+
* 输出内容的转换器
149135
*/
150-
logger?: KatexLogger<MarkdownItEnv>;
136+
transformer?: TeXTransformer;
151137
}
152138
```
153139

‎docs/src/zh/mathjax.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: "@mdit/plugin-mathjax"
33
icon: square-root-variable
44
---
55

6-
使用 Mathjax 呈现数学表达式的插件，你应该将 `mathjax-full` 安装为 peer 依赖。
6+
使用 Mathjax 呈现数学表达式的插件。
77

88
::: note
99

@@ -105,7 +105,7 @@ interface MarkdownItMathjaxOptions {
105105
- 在所有渲染完成后调用 `mathjaxInstance.outputStyle()`，以获得最终的 CSS 内容。
106106
- 如有必要，调用 `mathjaxInstance.clearStyle()` 清除现有样式缓存。
107107

108-
我们也有一个 `@mdit/plugin-mathjax-slim` 包，其中 `mathjax-full` 是可选依赖。
108+
我们也有一个 `@mdit/plugin-mathjax-slim` 包，其中 `mathjax-full` 是可选对等依赖。
109109

110110
## 格式
111111

‎packages/katex-slim/__tests__/__snapshots__/katex.spec.ts.snap

+2-2
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ exports[`inline katex > should output htmlAndMathML 4`] = `
155155
`;
156156

157157
exports[`should work with mhchem 1`] = `
158-
"<p class='katex-block'><span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mstyle mathcolor="#cc0000"><mtext>\\ce</mtext></mstyle><mrow><mi>H</mi><mn>2</mn><mi>O</mi></mrow></mrow><annotation encoding="application/x-tex">\\ce{H2O}
159-
</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord text" style="color:#cc0000;"><span class="mord" style="color:#cc0000;">\\ce</span></span><span class="mord"><span class="mord mathnormal" style="margin-right:0.08125em;">H</span><span class="mord">2</span><span class="mord mathnormal" style="margin-right:0.02778em;">O</span></span></span></span></span></span></p>
158+
"<p class='katex-block'><span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi mathvariant="normal">H</mi><msub><mpadded width="0px"><mphantom><mi>X</mi></mphantom></mpadded><mpadded height="0px"><mn>2</mn></mpadded></msub><mi mathvariant="normal">O</mi></mrow><annotation encoding="application/x-tex">\\ce{H2O}
159+
</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8333em;vertical-align:-0.15em;"></span><span class="mord"><span class="mord mathrm">H</span><span class="mord"><span class="mord"><span class="mord rlap"><span class="inner"><span class="mord" style="color:transparent;"><span class="mord mathnormal" style="margin-right:0.07847em;color:transparent;">X</span></span></span><span class="fix"></span></span></span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:-0.15em;"><span style="top:-2.55em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight"><span class="mord mtight"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0em;"><span style="top:-2.7em;"><span class="pstrut" style="height:2.7em;"></span><span><span class="mord mtight"><span class="mord mtight">2</span></span></span></span></span></span></span></span></span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathrm">O</span></span></span></span></span></span></p>
160160
"
161161
`;

‎packages/katex-slim/__tests__/katex.spec.ts

+9-6
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import MarkdownIt from "markdown-it";
22
import { beforeEach, describe, expect, it, vi } from "vitest";
33

4-
import { katex } from "../src/index.js";
4+
import { katex, loadMhchem } from "../src/index.js";
55

66
const markdownIt = MarkdownIt({ linkify: true }).use(katex);
77
const markdownItHTML = MarkdownIt({ linkify: true }).use(katex, {
@@ -242,12 +242,15 @@ $$
242242
expect(logger2).toHaveBeenCalledTimes(1);
243243
});
244244

245-
it("should work with mhchem", () => {
246-
const markdownItMhchem = MarkdownIt({ linkify: true }).use(katex, {
247-
mhchem: true,
248-
});
245+
it("should work with mhchem", async () => {
246+
const originalResult = markdownIt.render(`$$\\ce{H2O}$$`);
247+
248+
await loadMhchem();
249+
250+
const newResult = markdownIt.render(`$$\\ce{H2O}$$`);
249251

250-
expect(markdownItMhchem.render(`$$\\ce{H2O}$$`)).toMatchSnapshot();
252+
expect(newResult).not.equal(originalResult);
253+
expect(newResult).toMatchSnapshot();
251254
});
252255

253256
it("should work with transformer", () => {

‎packages/katex-slim/src/options.ts

-9
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,6 @@ export type TeXTransformer = (content: string, displayMode: boolean) => string;
1919
export interface MarkdownItKatexOptions<MarkdownItEnv = unknown>
2020
extends KatexOptions,
2121
Pick<MarkdownItTexOptions, "allowInlineWithSpace" | "mathFence"> {
22-
/**
23-
* Whether enable mhchem extension
24-
*
25-
* 是否启用 mhchem 扩展
26-
*
27-
* @default false
28-
*/
29-
mhchem?: boolean;
30-
3122
/**
3223
* Error logger
3324
*

‎packages/katex-slim/src/plugin.ts

+4-6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
/* eslint-disable @typescript-eslint/consistent-type-imports */
2-
import { createRequire } from "node:module";
32

43
import { escapeHtml } from "@mdit/helper";
54
import { tex } from "@mdit/plugin-tex";
@@ -8,8 +7,6 @@ import type MarkdownIt from "markdown-it";
87

98
import type { MarkdownItKatexOptions, TeXTransformer } from "./options.js";
109

11-
const require = createRequire(import.meta.url);
12-
1310
let isKatexInstalled = true;
1411
let katexLib: typeof import("katex");
1512

@@ -75,6 +72,10 @@ const katexBlock = (
7572
return transformer?.(result, true) ?? result;
7673
};
7774

75+
export const loadMhchem = async (): Promise<void> => {
76+
await import("katex/contrib/mhchem");
77+
};
78+
7879
export const katex = <MarkdownItEnv = unknown>(
7980
md: MarkdownIt,
8081
options: MarkdownItKatexOptions<MarkdownItEnv> = {},
@@ -89,7 +90,6 @@ export const katex = <MarkdownItEnv = unknown>(
8990
const {
9091
allowInlineWithSpace = false,
9192
mathFence = false,
92-
mhchem = false,
9393
logger = (
9494
errorCode: string,
9595
): "ignore" | "warn" | "error" | boolean | undefined =>
@@ -98,8 +98,6 @@ export const katex = <MarkdownItEnv = unknown>(
9898
...userOptions
9999
} = options;
100100

101-
if (mhchem) require("katex/contrib/mhchem");
102-
103101
md.use(tex, {
104102
allowInlineWithSpace,
105103
mathFence,

‎packages/katex-slim/src/shims.d.ts

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
declare module "katex/contrib/mhchem" {
2+
export {};
3+
}

‎packages/katex/__tests__/__snapshots__/katex.spec.ts.snap

+2-2
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ exports[`inline katex > should output htmlAndMathML 4`] = `
155155
`;
156156

157157
exports[`should work with mhchem 1`] = `
158-
"<p class='katex-block'><span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mstyle mathcolor="#cc0000"><mtext>\\ce</mtext></mstyle><mrow><mi>H</mi><mn>2</mn><mi>O</mi></mrow></mrow><annotation encoding="application/x-tex">\\ce{H2O}
159-
</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord text" style="color:#cc0000;"><span class="mord" style="color:#cc0000;">\\ce</span></span><span class="mord"><span class="mord mathnormal" style="margin-right:0.08125em;">H</span><span class="mord">2</span><span class="mord mathnormal" style="margin-right:0.02778em;">O</span></span></span></span></span></span></p>
158+
"<p class='katex-block'><span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi mathvariant="normal">H</mi><msub><mpadded width="0px"><mphantom><mi>X</mi></mphantom></mpadded><mpadded height="0px"><mn>2</mn></mpadded></msub><mi mathvariant="normal">O</mi></mrow><annotation encoding="application/x-tex">\\ce{H2O}
159+
</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8333em;vertical-align:-0.15em;"></span><span class="mord"><span class="mord mathrm">H</span><span class="mord"><span class="mord"><span class="mord rlap"><span class="inner"><span class="mord" style="color:transparent;"><span class="mord mathnormal" style="margin-right:0.07847em;color:transparent;">X</span></span></span><span class="fix"></span></span></span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:-0.15em;"><span style="top:-2.55em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight"><span class="mord mtight"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0em;"><span style="top:-2.7em;"><span class="pstrut" style="height:2.7em;"></span><span><span class="mord mtight"><span class="mord mtight">2</span></span></span></span></span></span></span></span></span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathrm">O</span></span></span></span></span></span></p>
160160
"
161161
`;

‎packages/katex/__tests__/katex.spec.ts

+9-6
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import MarkdownIt from "markdown-it";
22
import { beforeEach, describe, expect, it, vi } from "vitest";
33

4-
import { katex } from "../src/index.js";
4+
import { katex, loadMhchem } from "../src/index.js";
55

66
const markdownIt = MarkdownIt({ linkify: true }).use(katex);
77
const markdownItHTML = MarkdownIt({ linkify: true }).use(katex, {
@@ -242,12 +242,15 @@ $$
242242
expect(logger2).toHaveBeenCalledTimes(1);
243243
});
244244

245-
it("should work with mhchem", () => {
246-
const markdownItMhchem = MarkdownIt({ linkify: true }).use(katex, {
247-
mhchem: true,
248-
});
245+
it("should work with mhchem", async () => {
246+
const originalResult = markdownIt.render(`$$\\ce{H2O}$$`);
247+
248+
await loadMhchem();
249+
250+
const newResult = markdownIt.render(`$$\\ce{H2O}$$`);
249251

250-
expect(markdownItMhchem.render(`$$\\ce{H2O}$$`)).toMatchSnapshot();
252+
expect(newResult).not.equal(originalResult);
253+
expect(newResult).toMatchSnapshot();
251254
});
252255

253256
it("should work with transformer", () => {

‎packages/katex/src/options.ts

-9
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,6 @@ export type TeXTransformer = (content: string, displayMode: boolean) => string;
1919
export interface MarkdownItKatexOptions<MarkdownItEnv = unknown>
2020
extends KatexOptions,
2121
Pick<MarkdownItTexOptions, "allowInlineWithSpace" | "mathFence"> {
22-
/**
23-
* Whether enable mhchem extension
24-
*
25-
* 是否启用 mhchem 扩展
26-
*
27-
* @default false
28-
*/
29-
mhchem?: boolean;
30-
3122
/**
3223
* Error logger
3324
*

0 commit comments

Comments
 (0)