前言

在使用 Hexo 搭建本网站时，笔者遇到了一些关于 KaTeX 公式渲染的问题。找到解决方案后，特撰写此文记录，供自己和他人参考。

配置过程

以下是笔者参考官方文档配置 KaTeX 的过程，此部分内容部分转载自 Butterfly 文档（三）主题配置。

在 _config.butterfly.yml 中将 use 设置为 katex：

math:
  # Choose: mathjax, katex
  # Leave it empty if you don't need math
  use: katex
  per_page: true
  hide_scrollbar: false

卸载 marked 插件，安装 hexo-renderer-markdown-it：

npm un hexo-renderer-marked --save # 如果有安装这个的话，卸载
npm un hexo-renderer-kramed --save # 如果有安装这个的话，卸载

npm i hexo-renderer-markdown-it --save # 需要安装这个渲染插件
npm install katex @renbaoshuo/markdown-it-katex #需要安装这个katex插件

在 Hexo 根目录的 _config.yml 中添加以下配置：

1
2
3

markdown:
  plugins:
    - '@renbaoshuo/markdown-it-katex'

问题：网页内一级目录无法跳转

更换 Markdown 插件后，笔者的网页出现一级目录无法跳转的情况。解决方法是在 _config.yml 中的 markdown 配置中添加以下代码：

markdown:
  plugins:
    - '@renbaoshuo/markdown-it-katex'
  anchors:
    level: 1

添加后问题即可解决。

居中

最初笔者使用 KaTeX 时，采用 $\mathrm{ }$ 进行公式编辑，
效果如 $\mathrm{R_ {DS} = 3.1\ m \Omega}$ ，公式会嵌入文本中。如果将公式单独书写在一行中，例如：

1	$\mathrm{R_ {DS} = 3.1\ m \Omega}$

渲染效果是公式左对齐，无法自动居中。

尝试使用 ${ }$ 进行公式编辑，效果与 $\mathrm{ }$ 类似，依然无法居中。

查阅资料后发现，单个美元符号 ${ }$ 包裹表示行内公式，而两个美元符号 $$ $$ 包裹表示独立成行的公式。将公式改为独立成行的写法后，可以正常居中渲染，例如：

1	$$ R_ {DS} = 3.1\ m \Omega $$

效果如下：

$R_ {DS} = 3.1\ m \Omega$

换行

在 KaTeX 的语法中，使用 \\ 或 \newline 表示硬换行。但在 Hexo + Butterfly 搭建的此网页中，这两种方法无法实现换行，公式仍显示在同一行。

尝试使用独立成行公式的写法 $$ $$，可以实现公式间的换行，例如：

1
2
3

$$ R_ {DS} = 3.1\ m \Omega $$

$$ R_ {DS} = 3.1\ m \Omega $$

效果如下：

$R_ {DS} = 3.1\ m \Omega$

此外，KaTeX 0.10.0+ 版本会在关系或二元运算符（如 = 或 +）之后插入自动换行符。使用 \allowbreak 可以允许在关系或运算符以外的位置自动换行。

如果公式过长仍未自动换行，建议检查是否在公式内书写了过多文字。推荐将文字写在公式外部。如果确实需要在公式内书写文字，可以使用 \allowbreak 来允许任意位置的自动换行。

总结

若想让公式嵌入文本，推荐使用 $\mathrm{ }$ 或 ${ }$ 。
若想让公式单独成行且居中，推荐使用 $$ $$。
KaTeX 支持运算符后的自动换行，公式内尽量避免书写大段文字。必要时可使用 \allowbreak 允许任意位置的自动换行。