记忆:记录 Gitea 网页端公式渲染三条硬规则与配套工具

This commit is contained in:
2026-10-16 17:58:23 +08:00
parent 4b5c758f05
commit 50bd8a033a
2 changed files with 53 additions and 0 deletions
+42
View File
@@ -176,3 +176,45 @@
- 两总体考点**已补入手册,但尚未配题**——如需,可在 `02-试题`/`03-解析` 补 2–3 道(区间估计 1 + 检验 1 + MLE 不变性 1)。
- 本轮改动(手册/README/总览/PDF)**未推送**。
- `每日小练` 两套并列 02 与 `总览` 不一致仍待处理;第 4 讲(数字特征)仍缺文件夹。
---
## 修复 Gitea 网页端公式/加粗不渲染(线索:用户在网页上发现 §1.3 那几句公式原样显示)
**排查过程**:先排除本地链路——md2pdf 产物 HTML 全部 `tex-err=0 / 残留$=0`,KaTeX 0.19 也能正常渲染
`\overset`。再抓 Gitea 页面 HTML,发现它把**一部分** `$...$` 转成了 `<code class="language-math">`,
另一部分原样留着。统计 444 个有效样本后规律零例外,最后读 Gitea 源码坐实。
### 根因一:行内公式(`modules/markup/markdown/math/inline_parser.go`)
```go
// 收尾 $ 的后一个字节必须在集合内,否则 break → 整对 $ 作废
isValidEndingChar := isPunctuation(c) || c == ')' ||
c == ' ' || c == '\n' || c == 0 || c == '$'
// isPunctuation 只认 ASCII 的 . ! ? , ; :
// 开头 $ 的左邻若是 ASCII 字母/数字或 . ! ? , ; : → 直接 reject
```
中文与全角标点都是多字节字符(首字节 ≥ 0x80),一律落空 → 整对 `$` 退化为普通文本。
**修法:收尾 `$` 与后面紧跟的中文字符之间补一个半角空格**(唯一可行字符集)。
### 根因二:多行块级公式(`modules/markup/markdown/math/block_parser.go` 的 `Open()`)
同一行找不到收尾 `$$` 时(`idx = -1`),那个"检查行尾是否还有非空白字符"的循环**仍会执行**
(起点退化为 `pos+1`),于是 `$$\boxed{\begin{aligned}` 这种"开头 `$$` 带内容"的写法被整块拒绝。
**修法:多行块的开头 `$$` 与收尾 `$$` 一律独占一行**(KaTeX 会 trim,渲染结果不变)。
### 根因三:加粗失效(CommonMark right-flanking)
`**…"一致性"**的` 这种"收尾 `**` 前是标点、后是汉字"的写法不满足 right-flanking,星号外露。
**修法:在收尾 `**` 后补一个半角空格。**
### 产出
- 新增 `.workbuddy/tools/md2pdf/fix_gitea_math.py`(`--check` / `--apply`,`--scope=prob` 限定范围)
- 新增 `rebuild_prob_pdfs.sh`(批量重生成概率论 12 个 PDF)、`verify_gitea_math.py`(抓页面核验残留数)
- 处理范围:概率论在学练习 + 每日小练 + 知识点 = 23 个文件 1889 处空格 + 10 处加粗 + 6 个块级公式换行
- 网页实测 9 个文件 **残留 $ = 0**
- **仍有 1484 处待修**(试卷/模拟卷/多元函数积分学/总览),同规则,去掉 `--scope=prob` 即可
- 已推送(`a750fb2` 行内+加粗 / `4ddf42c` 块级 / `4b5c758` 验证脚本);第6讲手册内容改动同批推送(`ab10f27`)
+11
View File
@@ -16,6 +16,9 @@
## 用户偏好
- 数学内容**必须准确渲染公式**;Markdown 用 `$…$` / `$$…$$`。
- **写 `.md` 时,行内公式 `$…$` 的收尾 `$` 后面必须紧跟半角空格**,再写中文或全角标点(云端 Gitea 的硬性要求,见工具链)。例:`若 $X_n\to X$ ,则…`
- **多行 `$$…$$` 块的开头与收尾 `$$` 必须独占一行**(Gitea 硬性要求)。
- 标题/正文里 `**加粗**` 的收尾 `**` 后若是汉字,补一个半角空格(避免 CommonMark flank 规则导致星号外露)。
- 题目要求**难度分层**(A 基础 / B 中等 / C 拔高),题量可比小练多。
- 出题**防过拟合**:数字/区域原创,只对齐考法;要标「真题骨架」锚点。
- 讲解要**从零拆解 + 指出易错点**,并配图(show_widget 用 SVG)。
@@ -29,6 +32,14 @@
- `shot.js` 用于 HTML 视觉验收截图
- 依赖装在托管 node 工作区:`C:/Users/Wang Ling/.workbuddy/binaries/node/workspace`
- 本机**无 pandoc / 无 LaTeX**,勿尝试 xelatex 路线
- **Gitea 网页端公式渲染的硬规则**(云端 `app.zhantiandoudi.cn` 走 Gitea 自己的 Goldmark 扩展,**与本地 md2pdf 的 KaTeX 链路不同**,本地正常不代表网页正常)
- 行内 `$...$`:收尾 `$` 的后一个字符必须是**半角空白**(空格/换行);紧贴中文或全角标点 → 整对 `$` 不渲染。开头 `$` 的左邻若是 ASCII 字母/数字或 `. ! ? , ; :` 也不渲染
- 多行 `$$...$$`:同一行上 `$$` 后面若还有内容,整个块被拒绝(Gitea `block_parser.Open()` 的 `idx=-1` 分支缺陷)
- `**加粗**`:收尾 `**` 前是标点、后紧贴汉字 → 不生效(CommonMark right-flanking),星号外露
- 一键检测/修复:`python .workbuddy/tools/md2pdf/fix_gitea_math.py --check|--apply [--scope=prob]`
- 网页核验(抓页面数残留 `$`):`python .workbuddy/tools/md2pdf/verify_gitea_math.py`
- 批量重生成概率论 PDF:`bash .workbuddy/tools/md2pdf/rebuild_prob_pdfs.sh`
- 上述三类修复 KaTeX 输出不变(会 trim),故 PDF 可不必重生成
## 云仓库