如何在 Butterfly 主题中使用 KaTeX 数学公式

更新于2024-06-19

最近学习了部分算法知识，写到博客上却发现上面的数学公式渲染不出来，于是开始折腾网站，几经辗转，终于找到了正确的配置方式，写在这里记录一下。【也算帮后来人避避坑】

最开始研究的时候直接搜索“Hexo如何渲染数学公式”，虽然强调的Hexo框架的普遍性但是忽略了Butterfly主题的特殊性，最后找到的博客用的是hexo-renderer-markdown-it-plus，说要在 <head> 标签底部添加js代码，试了一下，GG

然后一看博客发布时间：2021-07-08，遂点进hexo-renderer-markdown-it-plus的Github页面看官方文档，然后发现，淦，已经停更了

好吧😅，我是🤡

所以在实践时一定要注意技术文档的时效性!

后面我直接搜索“hexo butterfly latex渲染插件”，然后在这里发现了关于hexo-renderer-markdown-it-katex的介绍(npm发布页)，按照博客说的试了一下，还是没渲染出来，再一看更新日期，行吧，2022-06-03【您搁这技术考古呢？】

然后换了几个blog，不过内容都大同小异【CSDN特有的高度相似】，最后找到了大佬的建站指南，更新日期2023-08-15，一年以内，比较新，看评论区反馈良好，遂再次尝试，终于成功渲染。

以上是探索历程，下面是实现方式

首先卸载旧渲染器，如果还装了什么其他的，也要一并卸载：

1
sudo npm un hexo-renderer-marked --save

然后安装hexo-renderer-markdown-it-katex

1
sudo npm i hexo-renderer-markdown-it-katex

然后再hexo的配置文件_config.yml添加：

1
2
3
4
5
6
7
8
9
10
11
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
  plugins:
  anchors:
    level: 1
    collisionSuffix: ''

（可选）在Butterfly的主题配置文件里配置MathJax，可以参考Butterfly官方配置文档

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Math (數學)
# --------------------------------------
# About the per_page
# if you set it to true, it will load mathjax/katex script in each page (true 表示每一頁都加載js)

# MathJax
mathjax:
  enable: true
  per_page: true

# KaTeX
katex:
  enable: true
  per_page: true
  hide_scrollbar: true

不过为了节约渲染性能，我没有选择给每一篇blog都开启公式渲染，我选择在Markdown Front-matter里加上mathjax: true

总结

  1. 技术路线不对就换关键词换顺序多搜几遍
  2. 看博客之前先看看更新时间，注意时效性
  3. 用开源技术的时候关注一下官方发布页的存活情况