markdown-exit-ratex

markdown-exit-ratex 是一个 markdown-exit 插件，用 RaTeX 在服务端把 TeX/LaTeX 公式渲染成 SVG。

它依赖 markdown-exit 的异步 renderer：请使用 renderAsync 或 renderInlineAsync。默认情况下插件会调用包内置的 RaTeX render-svg 可执行文件，所以博客构建环境只需要安装 npm/bun 包，不需要安装 Rust 或 Cargo。

特性

• 服务端直接生成 SVG，不需要前端加载 MathJax/KaTeX。
• 默认使用包内置 RaTeX 可执行文件，适合 CI/CD、静态博客和无 Cargo 环境。
• 支持 Linux x64 和 Linux arm64 的自动构建产物；wrapper 也支持 macOS/Windows 平台命名。
• 支持 $...$、\(...\)、$$...$$、\[...\]。
• 支持 Promise 缓存和并发限制，重复公式不会重复渲染。
• 可以覆盖为自定义 render 函数或外部 cli.command，方便本地调试 RaTeX。

安装

npm install markdown-exit markdown-exit-ratex

使用 bun 也可以：

bun add markdown-exit markdown-exit-ratex

基本用法

import { createMarkdownExit } from "markdown-exit";
import ratex from "markdown-exit-ratex";

const md = createMarkdownExit({ html: true });

md.use(ratex, {
  color: "#111827",
  fontSize: 40,
  concurrency: 4,
});

const html = await md.renderAsync(`
行内公式：$E = mc^2$

$$
\\int_0^\\infty e^{-x^2}\\,dx = \\frac{\\sqrt{\\pi}}{2}
$$
`);

如果不传 cli，插件会通过 bin/ratex-render-svg.mjs 自动选择：

vendor/ratex-render-svg-${platform}-${arch}

例如 Linux x64 会调用：

vendor/ratex-render-svg-linux-x64

在博客 CI/CD 中使用

静态博客构建通常运行在 Linux x64 容器或 GitHub Actions runner 上。发布包需要包含 vendor/ratex-render-svg-linux-x64，这样安装依赖后即可直接渲染：

md.use(ratex, {
  color: "#111827",
});

const html = await md.renderAsync(markdown);

不需要：

• Rust toolchain
• Cargo
• headless browser
• 前端公式渲染脚本

本地调试 RaTeX

开发 RaTeX 或想临时使用本地源码时，可以覆盖 CLI：

md.use(ratex, {
  cli: {
    command: "cargo",
    cwd: "/path/to/RaTeX",
    args: [
      "run",
      "--release",
      "-p",
      "ratex-svg",
      "--features",
      "cli embed-fonts",
      "--",
    ],
  },
});

E2E 预览

仓库内置了一个端到端预览测试：读取 Markdown，输出完整 HTML 文件。

npm run test:e2e

默认使用 ../RaTeX 作为 RaTeX workspace。需要换路径时：

RATEX_DIR=/path/to/RaTeX npm run test:e2e

输出文件：

test/output/e2e.html

要专门验证包内置二进制路径：

npm run test:e2e:bundled

输出文件：

test/output/e2e-bundled.html

GitHub Actions

已提供 workflow：

.github/workflows/build.yml

它会：

1. 在 ubuntu-24.04 构建 vendor/ratex-render-svg-linux-x64。
2. 在 ubuntu-24.04-arm 构建 vendor/ratex-render-svg-linux-arm64。
3. 汇总二进制到 npm 包的 vendor/。
4. 执行 npm test 和 npm run test:e2e:bundled。
5. 执行 npm pack --dry-run 并上传 .tgz 包。
6. 当 push v* tag 时，通过 npm Trusted Publishing / OIDC 发布到 npm。

workflow 默认从 erweixin/RaTeX@main 构建 RaTeX。手动触发时可以在 GitHub Actions 页面指定 ratex_repository 和 ratex_ref。

根据 GitHub 官方 runner 文档，公开仓库支持 ubuntu-24.04 x64 和 ubuntu-24.04-arm arm64 runner；私有仓库也支持对应 Linux runner，但计费和资源规格不同。

npm Trusted Publishing

发布 workflow 使用 npm Trusted Publishing，不需要 NPM_TOKEN。

需要在 npmjs.com 的 package settings 中添加 Trusted Publisher：

Provider: GitHub Actions
Organization or user: Efterklang
Repository: markdown-exit-ratex
Workflow filename: build.yml
Environment: 留空，除非你在 workflow 里显式配置 environment

workflow 中的发布 job 已配置：

permissions:
  contents: read
  id-token: write

并使用 Node 24，以满足 npm Trusted Publishing 对 Node 和 npm CLI 版本的要求。使用 Trusted Publishing 时，npm 会自动生成 provenance，不需要额外传 --provenance，也不要设置 NODE_AUTH_TOKEN。

选项

| 选项 | 默认值 | 说明 | | --- | --- | --- | | inlineDelimiters | [['\\(', '\\)'], ['$', '$']] | 行内公式分隔符。 | | blockDelimiters | [['$$', '$$'], ['\\[', '\\]']] | 块级公式分隔符。 | | render | RaTeX CLI renderer | 自定义异步渲染函数。 | | cli.command | 当前 Node 可执行文件 | 外部渲染命令；不设置时使用包内置 wrapper。 | | cli.args | [] | 传给外部命令的基础参数。 | | cli.cwd | undefined | 外部命令工作目录。 | | cli.timeoutMs | undefined | 单次渲染超时时间。 | | fontSize | 40 | RaTeX 字号。 | | dpr | 1 | RaTeX device pixel ratio。 | | color | undefined | 传给 RaTeX 的公式颜色。 | | cache | true | 是否按公式和渲染选项缓存 SVG Promise。 | | cacheSize | 1000 | 最大缓存公式数。 | | concurrency | 4 | 最大并发 RaTeX 渲染任务数。 | | throwOnError | false | 渲染失败时是否抛错；默认输出错误占位。 | | inlineClass | ratex ratex-inline | 行内公式外层 class。 | | blockClass | ratex ratex-display | 块级公式外层 class。 | | errorClass | ratex ratex-error | 错误占位 class。 |

内置二进制命名

bin/ratex-render-svg.mjs 会按当前平台查找下列文件：

vendor/ratex-render-svg-darwin-arm64
vendor/ratex-render-svg-darwin-x64
vendor/ratex-render-svg-linux-arm64
vendor/ratex-render-svg-linux-x64
vendor/ratex-render-svg-windows-arm64.exe
vendor/ratex-render-svg-windows-x64.exe

构建命令：

cargo build --release -p ratex-svg --features "cli embed-fonts"

然后把生成的 render-svg 复制为对应平台文件名，放到 vendor/ 并设置可执行权限。

为什么这样设计

• markdown-exit 支持异步 renderer，公式渲染可以自然走 Promise。
• SVG 在服务端生成，静态 HTML 输出即可直接预览和部署。
• RaTeX standalone SVG 可内嵌 glyph path，不依赖 webfont CSS。
• 内置 Linux 二进制后，博客 CI/CD 只需要安装 npm/bun 包。
• 仍保留外部 CLI 和自定义 renderer，方便调试和后续替换为原生绑定。