常见问题

HTML 文件设置

确保在 HTML 文件顶部包含 <!DOCTYPE html>，以防止浏览器进入 "quirks mode"，该模式可能导致 KaTeX 渲染错误。此声明在 <iframe> 中也必须添加（因其不继承父文档的 doctype）。

Markdown 预处理器问题

许多 Markdown 预处理器（如 Jekyll 或 GitHub Pages 使用的工具）具有 "smart quotes" 功能，会将 ' 转换为 ’，这会影响含撇号的数学公式（例如 f'）。解决方法是定义一个单字符宏将其恢复，例如在宏中定义 \textprime 或其他等价命令。

渲染差异与调整

KaTeX 在渲染 aligned 和 matrix 环境时遵循 LaTeX 标准，而 MathJax 风格不同。垂直布局中，行间间距可能较小，导致显示拥挤。可通过替换标准行分隔符为 \\[0.1em] 来增加间距（例如，原 \\ 改为 \\[0.1em]）。

KaTeX 不支持 align 环境，因为 LaTeX 不允许在数学模式中使用 align；改用 aligned 环境实现相同功能。

命令与选项对比

  • 颜色命令：KaTeX 的 \color 默认行为匹配 MathJax 启用 color.js 扩展的样式。将 colorIsTextColor 选项设为 true，可使 \color 行为类似 MathJax 的默认 \textcolor。
  • HTML 相关命令：MathJax 的 \class, \cssId, \style 分别对应 KaTeX 的 \htmlClass, \htmlId, \htmlStyle，以避免歧义。
  • 符号定义：某些符号使用宏（macro）定义而非 LaTeX 的 \DeclareMathSymbol，可能导致扩展行为不同（如影响 \expandafter 和 \noexpand），需注意潜在的多令牌扩展问题。

故障排除

检查 katex.css 是否加载：在文档任意位置添加以下 HTML 代码。如果加载成功，将显示 KaTeX 样式表版本（与 katex.js 版本匹配，可通过 katex.version 检查）；否则显示错误信息。

<!-- 检查 katex.css 加载状态 -->
<style>
  .katex-version { display: none; }
  .katex-version::after { content: "0.10.2 or earlier"; }
</style>
<span class="katex">
  <span class="katex-mathml">The KaTeX stylesheet is not loaded!</span>
  <span class="katex-version rule">KaTeX stylesheet version: </span>
</span>

CSS 定制

KaTeX 的 CSS 支持自定义，例如：

  • 使显示方程可水平滚动：
    /* 启用水平滚动条 */
.katex-display { overflow: auto hidden; }
  • 允许显示方程中换行（不同于 LaTeX 行为）：
    /* 允许行换行 */
.katex-display > .katex { white-space: normal; }
/* 增加行间间距 */
.katex-display > .base { margin: 0.25em 0; }
/* 减少显示数学周围空间 */
.katex-display { margin: 0.5em 0; }

总结

本指南详细介绍了 KaTeX 的常见问题及解决方案，包括 HTML 设置以规避渲染错误、Markdown 预处理器的引号问题处理、渲染差异调整（如行距优化和环境替代）、命令对比（颜色和 HTML 相关命令）、符号定义行为、故障排除方法以及 CSS 定制技巧（滚动和换行支持）。用户应优先确保文档结构正确，并利用宏和 CSS 定制来优化数学公式显示。💡

最后更新: