企业官网建设流程全解析

KaTeX 公式渲染实战：自动排版、化学式与 MathJax 迁移一次搞定

【免费下载链接】KaTeXFast math typesetting for the web.项目地址: https://gitcode.com/GitHub_Trending/ka/KaTeX

给博客、文档站或题库页加公式，最折腾的往往不是写 LaTeX，而是让散落在正文里的$...$真正排出来。KaTeX 是面向 Web 的快速数学公式渲染库，配合contrib/目录下的几个扩展，能覆盖自动排版、化学式、MathJax 迁移和无障碍朗读这几类常见需求。这篇文章面向刚上手 KaTeX 的开发者，读完你能独立接入 auto-render 扩展、补上 mhchem 化学式，并把老站从 MathJax 平滑切过来。

KaTeX 能替你做的几件渲染活儿

这一段先用一张表把核心能力和contrib/扩展对号入座，方便你按需求挑扩展，细节后文再讲。

核心库本身只负责把一段 LaTeX 渲染成一个元素，真正省事的是这些扩展：一个管自动扫描，一个管化学式，一个管老站兼容。

让正文公式自己排：接入 auto-render 扩展

auto-render 递归搜索指定元素里的文本节点，按分隔符把公式原位渲染出来，你不必再手动逐个katex.render。默认分隔符里已经有$$...$$、\(...\)等一组，但想启用单$内联公式时得自己改，且必须排在$$之后——规则按顺序匹配，$放前面会把$$当成空公式。

renderMathInElement(document.body, { delimiters: [ {left: "$$", right: "$$", display: true}, {left: "$", right: "$", display: false} ], ignoredTags: ["script", "pre", "code"] });

注意ignoredTags默认已包含pre、code等，长文站点建议再加ignoredClasses圈定渲染范围，避免对整页 DOM 做无谓递归。分隔符和选项的完整字段见 docs/autorender.md。

补上化学式与 MathJax 迁移的替代写法

这一节解决两个"核心库给不了"的场景：化学式和老站迁移。

引入 mhchem 渲染化学方程式

KaTeX 核心不认识\ce和\pu，这正是 mhchem 扩展存在的意义。它在语法上对齐 LaTeX 的 mhchem 包，2H2 + O2 -> 2H2O这类方程能被排成专业样式。加载顺序有讲究：脚本要放在katex.js之后、auto-render 之前。实现见 contrib/mhchem/mhchem.js。

从 MathJax 迁移到 KaTeX 的替代写法

老站里大量<script type="math/tex">是 MathJax 的惯用法，mathtex-script-type 扩展让你不改内容就能切到 KaTeX：

<script type="math/tex">x+\sqrt{1-x^2}</script>

加载核心库后再引入该扩展即可，迁移成本基本只剩脚本引入顺序这一处。

用 render-a11y-string 让公式能被读出来

无障碍这块常被忽略。renderA11yString("\frac{1}{2}")会输出 "start fraction, 1, divided by, 2, end fraction" 这类供屏幕阅读器朗读的文本，逗号分隔是为提升可听性。实现与符号映射表在 contrib/render-a11y-string/render-a11y-string.ts。

三步跑通：KaTeX 渲染最小可用路径

这一段给一个最小可验证的步骤，控制在五步以内，先跑通再谈扩展。

1. 引入核心样式表与katex脚本，版本用0.18.2（与 package.json 一致）。
2. 写一个\frac{1}{2}用katex.render渲染，确认字体和 CSS 加载正常。
3. 再加 auto-render 脚本，调renderMathInElement扫描正文。
4. 按需追加 mhchem 或 mathtex-script-type，注意加载顺序。
5. 用 docs/supported.md 对照你的公式是否被支持，不支持的换写法或宏。

避坑清单：扩展加载顺序与常见渲染问题

这一段按"现象→原因→处理"列几条高频坑。

• 扩展先于核心库加载导致函数未定义：renderMathInElement依赖全局katex，务必让核心脚本先执行，再用defer或onload兜底。
• 核心与扩展版本不一致：扩展从同一版本的dist/contrib取，混用旧版容易出现符号缺失或行为漂移。
• 单$内联公式不生效：多半是delimiters里$排在$$前面，调整顺序即可。
• 长页首屏卡顿：默认对整页递归，用ignoredClasses把渲染限定到公式容器。

API 细节与渲染选项分别见 docs/api.md 和 docs/options.md。

延伸：文档入口与相关资源

想继续深入，按下面几个入口走：

• 支持的 LaTeX 命令与语法：docs/supported.md
• auto-render 扩展完整 API：docs/autorender.md
• 渲染选项配置：docs/options.md
• 全部官方扩展源码：contrib/
• 扩展开发规范：CONTRIBUTING.md

把这些扩展当成按问题取用的工具箱，而不是全量引入，KaTeX 的渲染管线会一直保持轻快。

【免费下载链接】KaTeXFast math typesetting for the web.项目地址: https://gitcode.com/GitHub_Trending/ka/KaTeX