Hexo-Fluid 博客搭建过程中遇到的小问题

复杂数学公式渲染问题

渲染失败的原因是 Hexo 默认的 Markdown 渲染器不支持复杂公式，所以需要更换渲染器。
首先卸载默认渲染器:

1
npm uninstall hexo-renderer-marked --save

新渲染器Fluid官方配置手册中提供两种选择：mathjax和katex，其中mathjax需要额外安装Pandoc Release pandoc 3.7.0.1 · jgm/pandoc（如需安装，windows系统下载后缀为-windows-x86_64.msi的文件）

我首先尝试了mathjax，但是运行后npm audit 报告显示了 ejs(<= 3.1.9) 存在无法修复的漏洞，且影响了hexo-renderer-mathjax 插件中的 ejs 版本，mathjax渲染失败。

接下来我尝试了katex，在gitbash中运行：

1
2
npm install hexo-renderer-markdown-it --save
npm install @traptitech/markdown-it-katex --save

然后在根目录 _config.yaml中添加：

1
2
3
markdown:
  plugins:
    - "@traptitech/markdown-it-katex"

还要记得修改themes\fluid下的_config.yaml：

1
2
3
math:
    # Options: mathjax | katex
    engine: katex #默认为mathjax

接下来在gitbash中执行hexo clean，在有数学公式的文章 Front-matter 里指定 math: true，数学公式就能正常渲染了！

如果你不想每次都指定math: true，可以修改配置文件中的math: specific项:

1
2
3
4
math:
    # 开启后，只有在文章 Front-matter 里指定 `math: true` 才会在文章页启动公式转换，以便在页面不包含公式时提高加载速度
    # If true, only set `math: true` in Front-matter will enable math, to load faster when the page does not contain math
    specific: false

参考：配置指南 | Hexo Fluid 用户手册

一级目录无法跳转

查阅网上资料发现可能有两个原因：

  1. Fluid升级到1.9后与Hexo目录插件产生冲突。
    Fluid升级前生成目录使用的hexo-toc插件和Fluid 1.9+使用的目录功能冲突，导致目录无法正确跳转。
    解决办法：卸载hexo-toc
    在博客文件夹路径的gitbash中执行：
1
npm uninstall hexo-toc

这种解决办法适用于升级Fluid后突然失效的老用户。
来源：文章右侧的目录功能不能跳转 · Issue #775 · fluid-dev/hexo-theme-fluid

  1. hexo-renderer-markdown-it 配置问题
    本人也尝试卸载了hexo-toc，但是发现并没有用。我的博客刚部署完时还没有这个问题，且仅有一级目录无法跳转，应该并不是hexo-toc引起的。

后来发现有网友提出是hexo-renderer-markdown-it导致了目录跳转问题，将其卸载后目录跳转就正常了。但本人使用的数学公式渲染器katex必须依赖hexo-renderer-markdown-it，无法卸载。

在查阅hexo-renderer-markdown-it相关资料后发现这只是一个配置问题。
hexo-renderer-markdown-it的默认配置是从二级目录开始生成Heading ID，这也是为什么只有一级目录跳转不正常。
在博客根目录_config.yaml中添加（不要删除原来的内容）markdown-it的详细配置项，在默认配置情况下他们被省略：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Markdown-it config
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  plugins: #插件配置
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-sub
    - markdown-it-sup
  anchors: #锚
    level: 2 #生成链接的标题等级
    collisionSuffix: 'v'
    permalink: true
    permalinkClass: header-anchor
    permalinkSymbol:  #固定链接标记的符号，不喜欢可以修改

将level项改为1之后一级目录跳转就正常了！
目前我的配置文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  plugins:
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-sub
    - markdown-it-sup
    - "@traptitech/markdown-it-katex" 
    - markdown-it-emoji  # add emoji

  anchors:
    level: 1
    collisionSuffix: 'v'
    permalink: true
    permalinkClass: header-anchor
    permalinkSymbol:

如果不想修改，那么以后的博客从二级标题开始设置也没问题。

参考：hexo-renderer-markdown-it 插件 详解 - 简书

Hexo-Fluid 博客搭建过程中遇到的小问题
http://example.com/2025/05/23/Hexo-Fluid-博客搭建过程中遇到的小问题/
作者
Linjie ZHANG
发布于
2025年5月23日
许可协议