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

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

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

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

好吧😅,我是🤡

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

后面我直接搜索“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. 用开源技术的时候关注一下官方发布页的存活情况