Silencejql
0%

Hexo添加KaTeX插件-问题处理

发表于 分类于 Valine：
本文字数： 3.6k 阅读时长 ≈ 3 分钟

如果按照 Hexo添加KaTeX插件 仍未生效，可能是某些环节配置错误或冲突导致

1. 检查关键依赖安装

确保以下依赖已正确安装：

1
2
3
4
5
6
7
# 确保渲染器和插件存在
npm list hexo-renderer-markdown-it
npm list @traptitech/markdown-it-katex

# 如果未安装，重新执行：
npm un hexo-renderer-marked --save
npm i hexo-renderer-markdown-it @traptitech/markdown-it-katex --save

2. 确认 Hexo 全局配置

在 Hexo 根目录的 _config.yml 中，检查 markdown-it 的配置：

1
2
3
4
5
6
7
8
markdown:
  render:
    html: true  # 必须开启，否则公式中的 HTML 标签会被转义
  plugins:
    - "@traptitech/markdown-it-katex"  # 确保插件名称正确
  anchors:
    level: 2
    collisionSuffix: 'v'

3. 检查 Next 主题配置

在 themes/next/_config.yml 中，确保以下配置：

1
2
3
4
5
6
7
8
9
# 关闭 MathJax 和默认的数学公式渲染
math:
  mathjax:
    enable: false
  katex:
    enable: true  # 启用 KaTeX
    copy_tex: true
    # 如果 vendor_css 设为 true，需手动添加 CSS（不建议新手开启）
    vendor_css: false

4. 验证资源加载路径

(1) 检查 CSS 和 JS 是否引入

  • CSS 位置：
    打开生成的网页，按 F12 进入开发者工具 → Network 标签 → 刷新页面，检查是否有 katex.min.css 的请求。若未加载，说明主题模板未正确插入 CSS。

  • JS 位置：
    同样检查 katex.min.js 和 auto-render.min.js 是否加载。如果未加载，检查主题模板文件的修改是否正确。

(2) 修复资源路径

  • 如果使用的是旧版 Next 主题，模板文件路径可能是 .swig 或 .njk，确保修改了正确的文件：

    • CSS：themes/next/layout/_partials/head/head.njk（或 .swig）
    • JS：themes/next/layout/_partials/footer.njk（或 .swig）

  • 手动指定最新版本 CDN（避免缓存问题）：

    1
    2
    3
    4
    5
    6
    7
    <!-- CSS -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">

    <!-- JS -->
    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOzGykjIg/xn6ACkxIRv6gm2t6/E2lbLU5ZqH7sBE4k1pL5qfhMcJcH4dZnF" crossorigin="anonymous"></script>
    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCkM5qKq6gYVvokzNvAQu3fT8KX4l" crossorigin="anonymous" 
      onload="renderMathInElement(document.body, { delimiters: [{left: '$$', right: '$$', display: true}, {left: '$', right: '$', display: false}] });"></script>

5. 检查文章 Front-matter

在需要渲染公式的文章头部，确保已添加 katex: true：

1
2
3
4
5
---
title: 测试文章
date: 2023-01-01
katex: true  # 必须开启
---

6. 处理特殊符号转义

如果公式中的 _ 或 * 被错误转义，需调整渲染器配置：

1
2
3
4
5
6
7
8
# Hexo 根目录的 _config.yml
markdown:
  html: true
  xhtmlOut: false
  breaks: false
  linkify: true
  typographer: true
  quotes: '“”‘’'

7. 清理缓存并重新生成

Hexo 的缓存可能导致修改未生效：

1
hexo clean && hexo generate --debug

生成后，检查 public 目录下对应文章的 HTML 文件：

  • 搜索 katex.min.css 和 katex.min.js，确认资源已插入。
  • 检查公式是否被包裹在 <span class="katex">...</span> 中。

8. 常见问题排查

(1) 公式被渲染为纯文本

  • 原因：KaTeX 资源未加载或初始化失败。
  • 解决：按 F12 打开控制台，查看是否有 ReferenceError 或资源加载错误。如果发现 renderMathInElement is not defined，说明 auto-render.min.js 未正确加载。

(2) 公式显示错乱

  • 原因：$ 或 $$ 定界符被其他插件干扰。

  • 解决：在 markdown-it 配置中强制指定定界符：

    1
    2
    3
    4
    5
    6
    7
    8
    # Hexo 的 _config.yml
    markdown:
      plugins:
        - name: "@traptitech/markdown-it-katex"
          options:
            delimiters: 
              left: '$', right: '$', display: false
              left: '$$', right: '$$', display: true

(3) 与代码高亮冲突

  • 原因：某些代码块语法与 KaTeX 冲突。
  • 解决：在公式前后添加空行，避免与其他内容粘连。

9. 终极测试

创建一个最简单的测试文章，内容如下：

1
2
3
4
5
6
7
8
9
10
---
title: KaTeX 测试
date: 2023-01-01
katex: true
---

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

块级公式：
$$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$

如果仍不生效，可能是主题兼容性问题。尝试：

  1. 更新 Next 主题到最新版。
  2. 换用其他 KaTeX 集成方案（如 hexo-filter-mathjax）。

按以上步骤逐一排查，可解决 99% 的 KaTeX 未生效问题。如果问题依旧，请提供以下信息：

  1. 浏览器控制台截图（Network 和 Console 标签）。
  2. 测试文章的生成后的 HTML 片段。
  3. Hexo 和 Next 主题的版本号。