MathJax 配置资产：xaringan 幻灯片安装与复用

资产清单、拷贝安装、YAML 配套设置与公式编写 SOP

xaringan

MathJax

JavaScript

Quarto

Author

Harness 技术文档

Published

May 23, 2026

摘要

本仓库在 js/mathjax/ 目录集中维护 xaringan 幻灯片的 MathJax 配置资产，用于修复行内公式与 Quarto 式行间 $$ 在 remark.js 下的渲染问题。本文说明资产清单、配对拷贝、YAML 设置与公式 SOP。本地验证见配置资产验证工作流与测试指引。

1. 解决的核心问题

在使用 xaringan（基于 remark.js）编写幻灯片时，常见故障例如：

当 $a=1$ 且 $b=2$ 时……

往往只有第一个 $a=1$ 被 MathJax 渲染，后续公式仍以源码显示；Quarto 式三行 $$ 在 xaringan 中也可能无法渲染。Solution 1（推荐） 需同时使用下面两个文件（配对资产）。

2. Solution 1 配对资产（推荐）

组件	文件	作用	接入
MathJax 配置	`mathjax-config.js`	定界符、`skipTags`、AMS 扩展	YAML `nature.beforeInit`
Display-math 预处理	`wrap-display-math.R`	三行 `$$` → `$$...$$`	setup chunk `source()`

两个文件必须一起拷贝、一起配置。 缺任一组件时行间/行内公式可能部分或全部失败。

2.1 业务项目 YAML 示例

output:
  xaringan::moon_reader:
    nature:
      beforeInit: "js/mathjax-config.js"

在业务项目 .Rmd 的 setup chunk（chunk 头写 {r setup, include=FALSE}）中：

source(here::here("slide/slide-xaringan/Rscript/wrap-display-math.R"))
knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE)

（路径按实际拷贝位置调整。）

2.2 其它 JS 文件（遗留 / 备选）

文件	类型	说明
`mathjax-config-inline-math.js`	纯 `.js`	遗留；`options.skipHtmlTags` 为 MathJax 3 风格，与 xaringan 默认 MathJax 2.x 不一致
`mathjax-config-inline-math-b.html`	HTML	方案 B：`includes.in_header`

3. 标准版 `mathjax-config.js` 内容

window.MathJax = {
  tex2jax: {
    inlineMath: [['$', '$'], ['\\(', '\\)']],
    displayMath: [['$$', '$$'], ['\\[', '\\]']],
    processEscapes: true,
    processEnvironments: true,
    skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
  },
  TeX: {
    equationNumbers: { autoNumber: 'none' },
    extensions: ['AMSmath.js', 'AMSsymbols.js']
  }
};

3.1 文件命名约定

纯 JavaScript：不含 HTML 标签，供 beforeInit 使用。
HTML 片段：供 includes.in_header 使用。
所有脚本无本机绝对路径依赖。

4. 安装到业务项目（拷贝）

配对资产未纳入 Install-Harness.ps1，采用手动拷贝（见配置文件分发机制）。

4.1 推荐目录结构

slide-xaringan/
├── SEM-slide-eng-part0-IV.Rmd
├── js/mathjax-config.js
├── Rscript/wrap-display-math.R
└── libs/

4.2 PowerShell 拷贝（两文件一起）

$HarnessRoot = "D:\github\harness"
$SlideDir    = "D:\github\course-em-eng\slide\slide-xaringan"

Copy-Item "$HarnessRoot\js\mathjax\mathjax-config.js" "$SlideDir\js\mathjax-config.js" -Force
Copy-Item "$HarnessRoot\js\mathjax\wrap-display-math.R" "$SlideDir\Rscript\wrap-display-math.R" -Force

4.3 版本同步

现场 → 中央：验证有效的改动回灌 harness/js/mathjax/ 并更新本文档。
中央 → 现场：harness 升级后成对重新拷贝或 diff 合并。

5. 配套 YAML 与常见错误

5.1 仅 `beforeInit`（不足）

只配置 mathjax-config.js 无法自动处理 Quarto 式三行 $$，须同时 source(wrap-display-math.R)。

5.2 常见配置错误

现象	可能原因
行间公式不渲染	未 source `wrap-display-math.R`
行内公式异常	未配置 `beforeInit` 或路径错误
仅部分 Rmd 正常	每个源文件都须成对配置

6. 验证步骤

harness 内（推荐）：见 js/mathjax/test/ — L0 单元 + L1 模块化 render。

业务项目内：

xaringan::inf_mr() 或 knit。
检查 当 $a=1$ 且 $b=2$ 时 与三行 $$ 块。
查看 HTML <textarea id="source"> 是否含 `$$...$$`。

7. 公式编写 SOP

无论采用哪种方案，编写时须遵守 remark.js 的刚性规则：

紧贴原则：$ 必须紧贴公式首尾，中间严禁空格。
- ✅ $x+y$ | ❌ $ x+y $
转义下标：公式内多个下标 _ 应写成 \_，避免被 Markdown 识别为斜体。
- 示例： $x\_i + y\_j$
禁止跨行：行内公式内容必须在同一行内完成。
备选定界符：若 $ 仍不稳定，可改用 LaTeX 定界符 $ ... $（配置中已启用）。
特殊 class 限制：在 .footnote[...]、.red[...]、.pull-left[...] 等 remark 括号内，$...$ 的反斜杠可能被 remark 吃掉，公式变成 inline code； $...$ 亦可能失效。配对 hook 无法修复。对策：公式尽量写在 slide 正文；class 内可试 `$...$`；详见测试指引 §4.4。

更完整的方案对比见 xaringan-math-config.qmd 第 2、4 节。

8. 方案选型速查

维度	Solution 1（配对）	方案 B（HTML 头）
harness 资产	`mathjax-config.js` + `wrap-display-math.R`	`mathjax-config-inline-math-b.html`
行间 `$$`	支持（需 R hook）	视写法而定
推荐	新课程默认	特殊 HTML 注入需求

摘要