25.内容扩展：添加数学公式支持（KaTeX）

前言：主题原生支持但不完整

AnZhiYu 主题虽然原生支持 KaTeX，但默认配置缺少核心渲染库。

主题 KaTeX 渲染流程：

1. 检测配置
   themes/anzhiyu/layout/includes/third-party/math/index.pug
   └─ 判断 theme.katex.enable 和 page.katex

2. 加载模板
   themes/anzhiyu/layout/includes/third-party/math/katex.pug
   └─ 【问题在这里】原生模板只加载了 CSS，缺少 JS 渲染库

AnZhiYu 主题虽然原生支持 KaTeX 数学公式渲染，但默认的 KaTeX 模板不完整，缺少核心渲染库。本教程将引导您补全缺失部分，让数学公式和化学方程式正确显示。

效果演示：

行内公式：$E = mc^2$

块状公式：$$x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$$

化学方程式：$\ce{2H2 + O2 -> 2H2O}$

重要说明

配置文件路径：

• 原生主题：配置在 themes/anzhiyu/_config.yml
• 本博客方式：提取到根目录为 _config.anzhiyu.yml

请根据您的实际情况选择正确路径！
使用限制：

1. 块状公式必须单行书写

1
2
3
4
5
6
7
8
9
10
11

❌ 错误：
$$
   x = y
$$

✅ 正确：
$$x = y$$

2. **代码块内的示例公式不会渲染**
   - 用 ```markdown 包裹的示例代码不渲染
   - 实际使用时直接写在正文

第一步：启用 KaTeX 配置

打开 _config.anzhiyu.yml（或 themes/anzhiyu/_config.yml），找到 katex: 配置项（约第200行），修改为：

1
2
3
4
5

# KaTeX (数学公式渲染)
katex:
  enable: true # 启用 KaTeX
  per_page: false # 按需加载模式
  hide_scrollbar: true

参数说明：

• enable: true - 启用功能
• per_page: false - 仅在标记了 katex: true 的文章加载（提升性能）

第二步：修复 KaTeX 模板（关键）

为什么要修复？

主题原生的 themes/anzhiyu/layout/includes/third-party/math/katex.pug 文件只加载了：

• ✅ katex.min.css（样式）
• ✅ katex_copytex（复制功能）
• ❌ 缺少 katex.min.js（核心渲染引擎）
• ❌ 缺少 auto-render.min.js（自动识别公式）
• ❌ 缺少 mhchem.min.js（化学扩展）

所以公式会显示为原始代码，无法渲染！

修复方法：

打开 themes/anzhiyu/layout/includes/third-party/math/katex.pug，替换全部内容为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

link(rel="stylesheet" type="text/css" href=url_for(theme.asset.katex))
script(data-pjax).
  function initKatexRender() {
    if (typeof renderMathInElement !== 'function') {
      console.warn('[KaTeX] renderMathInElement 未加载，跳过渲染');
      return;
    }
    
    renderMathInElement(document.body, {
      delimiters: [
        {left: '$$', right: '$$', display: true},
        {left: '$', right: '$', display: false}
      ],
      throwOnError: false,
      strict: false,
      trust: true
    });
    
    document.querySelectorAll('#article-container span.katex-display').forEach(item => {
      anzhiyu.wrap(item, 'div', { class: 'katex-wrap'})
    });
  }
  
  function loadScript(src) {
    return new Promise((resolve, reject) => {
      const script = document.createElement('script');
      script.src = src;
      script.onload = resolve;
      script.onerror = reject;
      document.head.appendChild(script);
    });
  }
  
  Promise.resolve()
    .then(() => loadScript('https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js'))
    .then(() => loadScript('https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/mhchem.min.js'))
    .then(() => loadScript('https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js'))
    .then(() => loadScript('!{url_for(theme.asset.katex_copytex)}'))
    .then(() => {
      initKatexRender();
    })
    .catch(err => {
      console.error('[KaTeX] 脚本加载失败:', err);
    });
  

修复内容：

• ✅ 补全 katex.min.js（核心渲染引擎）
• ✅ 添加 mhchem.min.js（化学方程式扩展）
• ✅ 添加 auto-render.min.js（自动识别公式）
• ✅ 使用 PJAX 模式B（data-pjax + 立即执行）

使用方法

1. 在文章中启用

在文章 Front Matter 中添加 katex: true：

1
2
3
4

---
title: 我的数学文章
katex: true  # 启用公式支持
---

2. 行内公式

用单个 $ 包裹：

1
2
3

爱因斯坦方程：$E = mc^2$

勾股定理：$a^2 + b^2 = c^2$

效果： 爱因斯坦方程：$E = mc^2$

3. 块状公式

用双 $$ 包裹，必须写在同一行：

1

$$x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$$

效果：

$$x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$$

4. 化学方程式

使用 \ce{} 命令：

1
2
3

水的电解：$\ce{2H2O -> 2H2 ^ + O2 ^}$

酸碱中和：$\ce{HCl + NaOH -> NaCl + H2O}$

效果：

水的电解：$\ce{2H2O -> 2H2 ^ + O2 ^}$

酸碱中和：$\ce{HCl + NaOH -> NaCl + H2O}$

5. 常用符号

常见问题

问题1：公式显示为原始代码

原因： 忘记在 Front Matter 添加 katex: true

解决： 检查文章开头是否有：

1

katex: true

问题2：块状公式无法渲染

原因： 分多行写了

解决： 写在同一行：$$公式内容$$

问题3：PJAX 跳转后公式消失

原因： 未使用 data-pjax 属性

解决： 按第三步正确修复 katex.pug