xaringan 幻灯片：联网主力、断网容灾与教室包

一份 Rmd，两次渲染，再打一份可拷贝的离线目录

xaringan

MathJax

Quarto

Author

Harness 技术文档

Published

October 19, 2026

摘要

课件正文只有一份 .Rmd。联网观看、教室断网、以及拷到没有 Python 的教室机器，是三次输出，不是三份源稿。

可安装文件在 js/xaringan-dual/。MathJax 2 配置仍用 xaringan MathJax 资产。网站和离线公式的 MathJax 4 仍用 Quarto 本地 MathJax 4。

1. 三份输出

输出	怎么产生	公式与 remark	放哪里
联网 HTML	RStudio Knit，或 `render_xaringan_slide(path, "online")`	YAML 不写 `chakra`、不写 `mathjax`，因此用 remark.js 与 MathJax 2 的 CDN	与 Rmd 同名的 `.html`，可进 `_site/`
断网 HTML	`render_xaringan_slide(path, "offline")` 或 `"both"`	只覆盖 `chakra` 与 `mathjax`：本地 `remark-latest.min.js`，以及 `vendor/mathjax/load-mathjax.js`	`*-offline.html`，留在仓库目录，不进 `_site/`
教室包	`pack_remark_offline()`	离线 HTML 的相对路径原样保留	`_remark-offline/`，不进 git，不进 `_site/`

nature（高亮、比例、beforeInit）留在 YAML。beforeInit 写的是 MathJax 2 的 tex2jax。离线稿里 MathJax 4 加载器随后换掉 window.MathJax，两套引擎不同时生效。

../ 的层数按 Rmd 相对项目根计算。幻灯片放在 <模块>/slide-xaringan/ 时不必手写层数。

2. 安装

cd D:\github\harness
.\scripts\powershell\Install-Harness.ps1 `
  -InstallProfile mathjax-quarto,xaringan-dual `
  -ProjectRoot "D:\path\to\course"

mathjax-quarto 把运行时拷到 vendor/mathjax/。xaringan-dual 把脚本、remark.js、字体和行距 CSS 拷到 assets-remarkjs/。Profile all 不含这两项。

把 assets-remarkjs/decks.example.csv 复制为 assets-remarkjs/decks.csv。列是 part,section,title,stem。part 目录下要有 slide-xaringan/、mycss/ 和 pic/。

3. 接到现有幻灯片

YAML 与 setup 的形状见 assets-remarkjs/snippets/。联网稿保持：

不写 chakra，不写 mathjax
nature.beforeInit 指向 ../../assets-remarkjs/mathjax-config.js（Rmd 在 <模块>/slide-xaringan/ 时）
setup chunk source(here::here("assets-remarkjs/wrap-display-math.R"))
options(knitr.table.format = "html")。remark 会把 Markdown 管道表单元格里的 \( 当成转义括号

<模块>/mycss/my-font.css 顶部改为下面两行。正文、标题和代码底色留在课程自己的 CSS 里，安装不会覆盖该文件。

@import url("../../assets-remarkjs/fonts/local-fonts.css");
@import url("../../assets-remarkjs/xaringan-math-spacing.css");

CSS 不在 <模块>/mycss/ 时，按该文件到项目根的深度改 ../。

本地字体是 Ma Shan Zheng 与 Source Code Pro（SIL OFL），约 3.8MB，只装一份。不要再用指向 fonts.googleapis.com 的样式表。Songti SC、楷体、微软雅黑是系统回退，不在字体包里。

行距 CSS 里 MathJax 2 用 span.MJXc-display，MathJax 4 用 mjx-container[display="true"]。两条规则平行，选择器不合并。

引导页只链接不含 -offline 的 HTML。离线路径写 HTML 注释，不加脚注，不加可见链接。resources 排除 !slide-xaringan/*.Rmd 与 !slide-xaringan/*-offline.html。

.gitignore 用 slide-xaringan/*.html 盖住 *-offline.html，并忽略 _remark-offline/。不要写 !*-offline.html。

_quarto.yml 的 project.resources 只加 assets-remarkjs/mathjax-config.js 和 vendor/mathjax。字体与行距 CSS 随各模块 mycss/ 的 @import 进入站点，不要把整个 assets-remarkjs/ 放进 resources。

4. 日常命令

在项目根、here() 能找到该仓库时：

source("assets-remarkjs/render-slide.R")
render_xaringan_slide("slide-part1/slide-xaringan/lecture-01.Rmd", "offline")

source("assets-remarkjs/pack-offline.R")
pack_remark_offline()

离线 knitr 图在 <稿名>-offline_files/。教室包按这个目录名复制，不复制联网稿的 *_files/。

播放时双击 _remark-offline/index.html，或双击 start-offline.bat（它只用默认浏览器打开同一页）。不要改回 Python 本地服务器。

发布站点前先有联网 HTML，再 quarto render。确认 _site 里没有 *-offline.html，并且 _site/vendor/mathjax 存在。断网审查打开仓库里的 *-offline.html 或教室包，不要到 _site/ 里找离线稿。

5. 检查

不渲染幻灯片：

Rscript js/xaringan-dual/test/check-offline-helpers.R

它检查相对路径层数，以及缺少 decks.csv 或缺少列时脚本会停止。