DEBUG.WIKI
野草云;香港 200Mbps 峰值;不限月流量 · BGP VPS;查看套餐 →
雨云;给项目一台云服务器
晚安云;香港 CN2 ¥15/月

Prettier 改写 Markdown 公式中的上下标,跳过单美元段落格式化

Prettier 3.9.9 将单美元公式当普通 Markdown 处理,可能改写星号和下划线。按段使用 prettier-ignore,或只排除指定文档;双美元替换需另核渲染语义。

Prettier 3.9.9 格式化 Markdown 后,单美元包围的公式可能被悄悄改写:上标中的 * 变成 _,下标前又多出反斜杠。命令可以正常结束,文档仍然能打开,数学内容却已不同。

例如,下面两段原本交给文档系统按行内数学渲染:

$\alpha^*$ and $\beta^*$

**$\hat{x}_i$ and $\hat{y}_j$**

在这条故障路径中,会被格式化成:

$\alpha^_$ and $\beta^_$

**$\hat{x}\_i$ and $\hat{y}\_j$**

不要只对照页面上的空格和换行。* 与 _ 都可能参与 Markdown 的强调语法,但它们在 TeX 公式中并不等价。

单美元内容不再进入数学解析路径

3.9.9 的 Markdown 解析器设置了 singleDollarTextMath: false,目的是避免把普通文本中的美元符号误当数学分隔符。副作用是,真实的 $...$ 也不再因为单美元而获得数学内容的保护,内部符号会继续参与普通 Markdown 的处理。

已核对的正式 3.9.10 仍保留这个解析选项。它不是用户在 .prettierrc 中漏配了一个同名开关,也不能靠修改文档渲染器的数学插件,让此前的格式化步骤自动保留原字节。

对需要原样保留的段落跳过格式化

少量公式可以使用 Prettier 的 Markdown 节点忽略注释。每个需要保留的段落前单独放一条,避免只保护了第一段:

<!-- prettier-ignore -->
$\alpha^*$ and $\beta^*$

<!-- prettier-ignore -->
**$\hat{x}_i$ and $\hat{y}_j$**

注释不应被项目的前置处理先删除。保存后检查真正执行格式化的入口,包括编辑器保存动作、提交钩子和 CI;仅在某个本机命令里跳过,不能覆盖其他自动写回步骤。

公式很多、要求保留原始 Markdown 的文件,也可以在项目的 .prettierignore 中列出明确路径。例如,下面只排除这一份文档:

docs/equations.md

这会同时停止该文件其他部分的 Prettier 格式化,应由项目接受这个取舍,而不是扩大成忽略所有 Markdown。文件路径须与实际忽略配置所在位置及调用方式核对;回退时恢复原来的忽略规则与文档内容。

不要把单美元机械替换为双美元

不同文档系统对 $$...$$ 的解释可能不同。有的接受同一行里的双美元,有的把它当块级展示数学。替换后虽然可能避开当前解析路径,也可能改变段落布局、编号或数学识别规则。

如果项目确实要统一分隔符,应按实际渲染器的语法迁移,并检查所有发布目标;只为让格式化命令通过,不值得悄悄改变文档协议。通过自定义数学解析补丁覆盖 Prettier 内部实现,同样需要额外维护,不能当作现成的公开配置项。

从版本控制恢复已被改写的公式,再以既定入口检查格式化前后的原始差异。验收既看符号字节是否保留,也看最终文档里的行内位置、上下标和强调效果。退出码为零只能说明格式化没有抛错,不能证明公式含义未变。