feat(math): add optional native formula rendering

Author: jikkai

Cargo.lock

@@ -15,6 +15,11 @@ markdown = "1.0.0"
 mdxjs = "1.0.4"
 napi = { version = "3.12.0", default-features = false, features = ["napi8"] }
 napi-derive = "3.6.2"
+ratex-layout = "=0.1.14"
+ratex-parser = "=0.1.14"
+ratex-svg = { version = "=0.1.14", features = ["embed-fonts"] }
+ratex-types = "=0.1.14"
+roxmltree = "0.21.1"
 serde = { version = "=1.0.224", features = ["derive"] }
 serde_json = "1.0.145"
 sha2 = "0.10.9"

Cargo.toml

@@ -1,5 +1,5 @@
 ---
-description: Exact defaults and behavior for collections, MDX, highlighting, media, derived fields, manifests, cache, and generated output.
+description: Exact defaults and behavior for collections, MDX, math, highlighting, media, derived fields, manifests, cache, and generated output.
 ---
 
 # Configuration
@@ -30,6 +30,7 @@ At least one collection is required.
 | `root`               | `process.cwd()`   | Base for relative configuration paths.                   |
 | `collections`        | required          | Content directories, schemas, locales, and slugs.        |
 | `mdx`                | see below         | MDX parser and JSX runtime options.                      |
+| `math`               | disabled          | Build-time math rendering. Use `{}` to enable.           |
 | `highlight`          | Shiki enabled     | Syntax highlighting policy. Use `false` to disable.      |
 | `media`              | rewriting enabled | Markdown media import policy. Use `false` to disable.    |
 | `derived`            | all disabled      | Reading time and last-modified metadata.                 |
@@ -114,6 +115,45 @@ mdx: {
 Authored ESM and MDX JSX remain part of the compiled module. `providerImportSource` controls MDX
 component-provider wiring; it is not a switch for preserving or stripping JSX.
 
+## Math
+
+```ts
+math: {
+  singleDollar: true,
+  macros: {
+    '\\RR': '\\mathbb{R}',
+  },
+}
+```
+
+Math syntax is opt-in. Set `math: {}` to render inline `$x$` and display `$$` expressions, or
+`math: false` to keep dollar signs as ordinary text. `singleDollar: false` disables the `$x$`
+inline form, which is useful for prose containing currency. With the default enabled, write a
+literal currency sign as `\$`.
+
+`macros` maps one TeX control sequence to a fixed expansion. Each expansion is limited to 1 KiB,
+and names plus expansions are limited to 16 KiB in total. Parameter placeholders and dynamic
+definition commands such as `\\def` and `\\newcommand` are rejected. The map is copied and applied
+independently to each expression, so definitions cannot leak between documents.
+
+RaTeX parses, lays out, and renders each expression inside the Rust compiler. The generated module
+contains self-contained SVG output with no browser math runtime, stylesheet, webfont, raw HTML, or
+`dangerouslySetInnerHTML`. Invalid TeX reports `AMAMO_MATH_PARSE`; unsafe, external, or non-embedded
+SVG output reports `AMAMO_MATH_RENDER`. A glyph that cannot be embedded fails the build instead of
+falling back to an external font. Non-KaTeX Unicode glyphs can use an installed system font, so
+their exact outlines may differ between build machines. Only publish those glyphs when the build
+machine's fallback-font license permits embedding and redistribution.
+
+Each expression is limited to 64 KiB of TeX, 100,000 expanded tokens, an 8 MiB or 100,000-node
+parsed AST, 100,000 expanded array cells in total, 10,000 display items, 10,000 em in either
+dimension, a 16 MiB SVG, and 100,000 SVG nodes. Parse and structural limit failures report
+`AMAMO_MATH_PARSE`; layout or SVG limit failures report `AMAMO_MATH_RENDER`.
+
+Inline SVG uses RaTeX's depth for baseline alignment and inherits `currentColor`; explicit TeX
+colors remain explicit. The wrapper exposes `role="math"` and the source expression as an accessible
+label. RaTeX does not currently emit MathML, so formula text is not selectable and assistive
+technology receives the TeX label rather than a MathML tree.
+
 ## Highlighting
 
 ```ts

apps/docs/docs/configuration.mdx

@@ -1,5 +1,5 @@
 ---
-description: 集合、MDX、高亮、媒体、派生字段、manifest、缓存和生成产物的准确默认值与行为。
+description: 集合、MDX、数学公式、高亮、媒体、派生字段、manifest、缓存和生成产物的准确默认值与行为。
 ---
 
 # 配置
@@ -29,6 +29,7 @@ export default defineConfig({
 | `root`               | `process.cwd()` | 相对配置路径的基准目录。                         |
 | `collections`        | 必填            | 内容目录、schema、locale 和 slug。               |
 | `mdx`                | 见下文          | MDX 解析和 JSX runtime 选项。                    |
+| `math`               | 关闭            | 构建期数学渲染；设为 `{}` 启用。                 |
 | `highlight`          | 启用 Shiki      | 语法高亮策略；设为 `false` 可禁用。              |
 | `media`              | 启用重写        | Markdown 媒体 import 策略；设为 `false` 可禁用。 |
 | `derived`            | 全部关闭        | 阅读时间和最后修改时间。                         |
@@ -109,6 +110,40 @@ mdx: {
 手写的 ESM 和 MDX JSX 仍会进入编译模块。`providerImportSource` 控制 MDX 组件 provider 的
 接线，不是保留或删除 JSX 的开关。
 
+## 数学公式
+
+```ts
+math: {
+  singleDollar: true,
+  macros: {
+    '\\RR': '\\mathbb{R}',
+  },
+}
+```
+
+数学语法需要显式启用。`math: {}` 会渲染行内 `$x$` 与块级 `$$` 公式；`math: false` 会把美元
+符号继续当成普通文字。`singleDollar: false` 可关闭 `$x$` 行内形式，适合货币内容较多的站点。
+使用默认值时，文字中的美元符号应写成 `\$`。
+
+`macros` 把单个 TeX 控制序列映射到固定展开值。每个展开值不超过 1 KiB，命令名与展开值合计
+不超过 16 KiB。参数占位符以及 `\\def`、`\\newcommand` 等动态定义命令会被拒绝。配置会复制到每个
+公式的独立解析器中，因此定义不会在公式或文档之间泄漏。
+
+RaTeX 在 Rust 编译器内完成解析、排版与渲染。编译模块只包含自包含 SVG 输出，不需要浏览器
+数学运行时、样式表、webfont、原始 HTML 或 `dangerouslySetInnerHTML`。非法 TeX 产生
+`AMAMO_MATH_PARSE`；不安全、外部引用或无法嵌入字形的 SVG 产生 `AMAMO_MATH_RENDER`，不会
+静默回退到外部字体。KaTeX 字体未覆盖的 Unicode 字形可能使用构建机上的系统字体，因此不同
+构建机生成的轮廓可能不同。只有当构建机的回退字体许可嵌入与再分发时，才应发布这些字形。
+
+每个表达式最多包含 64 KiB TeX、100,000 个展开 token、8 MiB 或 100,000 个节点的解析 AST、
+合计 100,000 个展开后的 array 单元格、10,000 个排版项、任一方向 10,000 em、16 MiB SVG 与
+100,000 个 SVG 节点。语法与结构限制失败会产生 `AMAMO_MATH_PARSE`；排版或 SVG 限制失败会产生
+`AMAMO_MATH_RENDER`。
+
+行内 SVG 使用 RaTeX 的 depth 对齐基线，并通过 `currentColor` 继承文字颜色；显式 TeX 颜色仍会
+保留。外层元素提供 `role="math"`，并把原始表达式作为无障碍标签。RaTeX 当前不生成 MathML，
+因此公式文本不可选择，辅助技术接收到的是 TeX 标签而不是 MathML 树。
+
 ## 语法高亮
 
 ```ts

apps/docs/docs/configuration.zh-CN.mdx

@@ -12,13 +12,13 @@
   "dependencies": {
     "@amamo/doctrine": "0.2.1",
     "@base-ui/react": "1.7.0",
-    "lucide-react": "1.29.0",
+    "lucide-react": "1.31.0",
     "pagefind": "1.5.2",
     "react": "19.2.8",
     "react-dom": "19.2.8"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",
     "typescript": "^7.0.2"

apps/docs/package.json

@@ -22,6 +22,8 @@ pub struct NativeConfig {
     pub derived: NativeDerivedConfig,
     pub highlight: NativeHighlightConfig,
     pub manifests: HashMap<String, NativeManifestConfig>,
+    #[serde(default)]
+    pub math: NativeMathConfig,
     pub media: NativeMediaConfig,
     pub mdx: NativeMdxConfig,
     pub root: String,
@@ -91,6 +93,25 @@ pub struct NativeMdxConfig {
     pub provider_import_source: String,
 }
 
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NativeMathConfig {
+    pub enabled: bool,
+    #[serde(default)]
+    pub macros: HashMap<String, String>,
+    pub single_dollar: bool,
+}
+
+impl Default for NativeMathConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            macros: HashMap::new(),
+            single_dollar: true,
+        }
+    }
+}
+
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct NativeDerivedConfig {

native/src/config.rs

@@ -10,9 +10,11 @@ use swc_core::ecma::visit::{VisitMut, VisitMutWith};
 
 use crate::Diagnostic;
 use crate::config::{
-    NativeCollectionConfig, NativeMdxConfig, NativeMediaConfig, apply_schema_defaults_and_validate,
+    NativeCollectionConfig, NativeMathConfig, NativeMdxConfig, NativeMediaConfig,
+    apply_schema_defaults_and_validate,
 };
 use crate::hast::{remove_table_line_breaks, rewrite_media};
+use crate::math::replace_math;
 
 #[derive(Debug, serde::Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -89,11 +91,17 @@ pub fn prepare_mdx(
     file: &str,
     body: &str,
     config: &NativeMdxConfig,
+    math: &NativeMathConfig,
     highlight: bool,
     root: &Path,
     media: &NativeMediaConfig,
 ) -> Result<PreparedMdx, Vec<Diagnostic>> {
-    let options = mdx_options(file, config);
+    let mut options = mdx_options(file, config);
+    if math.enabled {
+        options.parse.constructs.math_flow = true;
+        options.parse.constructs.math_text = true;
+        options.parse.math_text_single_dollar = math.single_dollar;
+    }
     let mut mdast = mdxjs::mdast_util_from_mdx(body, &options)
         .map_err(|error| vec![mdx_diagnostic(file, error)])?;
     let reading_words = reading_units(&mdast);
@@ -105,6 +113,7 @@ pub fn prepare_mdx(
         apply_hard_breaks(&mut mdast);
     }
     let mut tree = mdxjs::mdast_util_to_hast(&mdast);
+    replace_math(&mut tree, file, math)?;
     remove_table_line_breaks(&mut tree);
     let media = rewrite_media(&mut tree, root, Path::new(file), media)?;
 
@@ -378,7 +387,9 @@ mod tests {
     use mdxjs::hast::Node;
     use serde_json::json;
 
-    use crate::config::{MediaMissing, NativeCollectionConfig, NativeMdxConfig, NativeMediaConfig};
+    use crate::config::{
+        MediaMissing, NativeCollectionConfig, NativeMathConfig, NativeMdxConfig, NativeMediaConfig,
+    };
 
     use super::{finish_mdx, parse_frontmatter, prepare_mdx};
 
@@ -440,6 +451,7 @@ mod tests {
             "/project/hello.mdx",
             source,
             &options,
+            &NativeMathConfig::default(),
             false,
             std::path::Path::new("/project"),
             &NativeMediaConfig::default(),
@@ -478,6 +490,7 @@ mod tests {
             "/project/table.mdx",
             source,
             &options,
+            &NativeMathConfig::default(),
             false,
             std::path::Path::new("/project"),
             &NativeMediaConfig::default(),
@@ -501,6 +514,7 @@ mod tests {
             "/project/hello.mdx",
             source,
             &options,
+            &NativeMathConfig::default(),
             false,
             std::path::Path::new("/project"),
             &NativeMediaConfig::default(),
@@ -540,6 +554,7 @@ mod tests {
             file.to_str().unwrap(),
             source,
             &options,
+            &NativeMathConfig::default(),
             false,
             &root,
             &media,
@@ -585,6 +600,7 @@ mod tests {
             "/project/content/post.mdx",
             "![](../../outside.png)",
             &options,
+            &NativeMathConfig::default(),
             false,
             std::path::Path::new("/project"),
             &media,

native/src/document.rs

@@ -225,10 +225,24 @@ fn is_code_block(node: &Node) -> bool {
         node,
         Node::Element(element)
             if element.tag_name == "pre"
-                && matches!(element.children.first(), Some(Node::Element(code)) if code.tag_name == "code")
+                && matches!(
+                    element.children.first(),
+                    Some(Node::Element(code))
+                        if code.tag_name == "code" && !has_class(code, "math-display")
+                )
     )
 }
 
+fn has_class(element: &Element, expected: &str) -> bool {
+    element.properties.iter().any(|(name, value)| {
+        name == "className"
+            && matches!(
+                value,
+                PropertyValue::SpaceSeparated(classes) if classes.iter().any(|class| class == expected)
+            )
+    })
+}
+
 pub fn rewrite_media(
     tree: &mut Node,
     root: &Path,

native/src/hast.rs

@@ -3,6 +3,7 @@ mod config;
 mod document;
 mod hast;
 mod manifest;
+mod math;
 
 use std::collections::{HashMap, HashSet};
 use std::path::Path;
@@ -341,6 +342,7 @@ pub fn prepare_batch(config_json: String, inputs_json: String) -> Result<Prepare
             &input.file,
             &parsed.body,
             &config.mdx,
+            &config.math,
             config.highlight.enabled,
             Path::new(&config.root),
             &config.media,