在 Hexo 的 Next 主题中集成 KaTeX 数学公式渲染
1. 更换 Markdown 渲染器
Hexo 默认的渲染器可能不支持 KaTeX,需更换为兼容的渲染器:
1 | npm un hexo-renderer-marked --save # 卸载默认渲染器 |
2. 配置 markdown-it
在 Hexo 根目录的 _config.yml
中添加配置:
1 | markdown: |
3. 修改 Next 主题配置
在 Next 主题的配置文件 (themes/next/_config.yml
) 中:
-
关闭 MathJax(避免冲突):
1
2
3math:
mathjax:
enable: false -
启用 KaTeX:
1
2
3
4katex:
enable: true
copy_tex: true # 允许复制公式代码
vendor_css: false # 如果手动加载 CSS 可设为 true
4. 引入 KaTeX 资源
在主题布局文件中添加 KaTeX 的 CSS 和 JS:
-
编辑
themes/next/layout/_partials/head/head.swig
,在<head>
内添加:1
2
3{% if theme.katex.enable %}
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">
{% endif %} -
编辑
themes/next/layout/_partials/footer.njk
(或类似文件),在末尾添加:1
2
3
4
5
6{% if theme.katex.enable %}
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js"
onload="renderMathInElement(document.body, { delimiters: [{left: '$$', right: '$$', display: true}, {left: '$', right: '$', display: false}] });">
</script>
{% endif %}
5. 文章启用 KaTeX
在文章的 Front-matter 中添加 katex: true
:
1 | --- |
6. 处理特殊符号转义
若公式中的 _
被转义,需调整渲染器配置。在 Hexo 的 _config.yml
中:
1 | markdown: |
7. 测试与清理缓存
生成并预览效果:
1 | hexo clean && hexo generate --debug && hexo server |
访问 http://localhost:4000
查看公式是否正确渲染。
常见问题
- 公式未渲染:检查控制台是否有资源加载错误,确认 CDN 链接有效。
- 符号错位:确保没有多余的转义字符,使用
\\
代替\
。 - 主题版本差异:不同 Next 版本配置项可能不同,参考官方文档调整。
完成以上步骤后,即可在 Hexo 博客中使用 KaTeX 渲染数学公式。