Hexo博客渲染KaTeX数学公式
fengxiaot Lv4
  2021-01-30 20:58:54 2021-01-30 20:58  

对于数学/物理系学生来说，一个常见的需求是想要在Hexo博客中支持复杂数学公式的渲染。MathJax 和 KaTeX\KaTeX 是两个常见的渲染引擎。本文给出基于Keep主题的 KaTeX\KaTeX 的配置方法。


更换渲染器

无论是基于MathJax 还是 KaTeX\KaTeX，都要首先更换Hexo自带的渲染器，因为它不支持渲染复杂数学公式。

1
npm uni hexo-renderer-marked

安装 hexo-renderer-markdown-it 渲染器

1
npm i hexo-renderer-markdown-it

此渲染器同时安装了如下插件

插件 功能
markdown-it-abbr 缩写
markdown-it-emoji Emoji 🐱🐭
markdown-it-deflist 定义列表
markdown-it-sub 下标
markdown-it-sup 上标
markdown-it-mark 高亮标记
markdown-it-footnote 脚注
markdown-it-ins 下划线
markdown-it-attrs 标题 HTML 属性
markdown-it-cjk-breaks 中日韩字符换行
markdown-it-container 容器

但它们不会默认开启，需要手动在 _config.yml 进行设置。同时，我还安装了如下插件

插件 功能
markdown-it-anchor 标题锚点
markdown-it-toc-done-right 目录
@renbaoshuo/markdown-it-katex 公式

并在根目录的 _config.yml 中添加如下内容

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
markdown:
  preset: 'default'
  render:
    html: true
    xhtmlOut: false
    langPrefix: 'language-'
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  enable_rules:
  disable_rules:
  plugins:
    - markdown-it-emoji
    - markdown-it-sub
    - markdown-it-sup
    - markdown-it-deflist
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-mark
    - markdown-it-anchor
    - markdown-it-toc-done-right
    - markdown-it-attrs
    - markdown-it-cjk-breaks
    - markdown-it-container
    - '@renbaoshuo/markdown-it-katex'
  anchors:
    level: 2
    collisionSuffix: ''
    permalink: false
    permalinkClass: 'header-anchor'
    permalinkSide: 'left'
    permalinkSymbol: '¶'
    case: 0
    separator: '-'
  images:
    lazyload: false
    prepend_root: false
    post_asset: false
  inline: false

接着执行

1
2
hexo clean
hexo generate

以清除缓存并刷新插件配置。


修改 Header

插件安装好后，需要在每篇博客的 <head> 标签中包含 KaTeX\KaTeX 的 CSS

1
2
<!-- KaTeX CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css">

若每篇博客都要使用数学公式，可以将其加入主题预定义的 head.ejs 中。


可选配置

Copy TeX

如果希望自己博客里的公式可被复制，可以启用 CopyTeX 插件

1
2
<!-- Copy-tex JS -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/contrib/copy-tex.min.js"></script>

横向滚动

在小屏幕上经常会出现公式过长的情况，这时需要设置公式的横向滚动。将下列样式加入主题预定义的 head.ejs 中修复此问题

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!-- Horizontal scroll for KaTeX display. -->
<style>
    .katex-display {
        overflow-x: auto;
        overflow-y: hidden;
        white-space: nowrap;
        padding-bottom: 0.3rem;
    }

    .katex-display > .katex {
        display: inline-block;
        padding-top: 0.2rem;
        padding-bottom: 0.2rem;
    }
</style>