Hexo 博客配置搜索与 LaTeX 渲染实战

前言

最近在配置 Hexo 博客时，遇到了搜索功能和 LaTeX 渲染的问题，记录一下完整的配置过程和踩坑经验。

一、搜索功能配置

1.1 安装搜索插件

1
npm install hexo-generator-searchdb --save

1.2 配置搜索索引

在 _config.yml 中添加：

1
2
3
4
5
6
# Search
search:
  path: search.json
  field: post
  content: true
  format: html

1.3 启用本地搜索

在 _config.anzhiyu.yml（主题配置）中：

1
2
3
4
local_search:
  enable: true
  preload: true
  CDN:

同时也要修改主题的 _config.yml：

1
2
3
4
local_search:
  enable: true
  preload: true
  CDN:

1.4 部署配置

在 _config.yml 中配置 GitHub 部署：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/用户名/用户名.github.io
  branch: master

安装部署插件：

1
npm install hexo-deployer-git --save

1.5 使用方法

  • 点击导航栏搜索按钮
  • 或使用快捷键 Alt + S / shift + S

二、LaTeX 渲染配置

2.1 安装 Katex 渲染器

1
npm install hexo-renderer-markdown-it-katex --save

重要：需要卸载默认的 hexo-renderer-marked，否则 LaTeX 不会被渲染：

1
npm uninstall hexo-renderer-marked

2.2 配置 Katex

在 _config.anzhiyu.yml 中：

1
2
3
4
katex:
  enable: true
  per_page: true  # 设为true，每页都会加载katex
  hide_scrollbar: true

2.3 LaTeX 语法

行内公式：$公式$

行间公式：$$公式$$

示例：

1
$$p(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp\left(-\frac{1}{2 \sigma^2} (x - \mu)^2\right).$$

三、常见问题排查

3.1 搜索按钮不显示

  • 检查 _config.anzhiyu.yml 中 local_search.enable 是否为 true
  • 同时检查主题目录下的 _config.yml
  • 清除缓存后重新部署：hexo clean && hexo generate && hexo deploy

3.2 LaTeX 不渲染

  • 确保已卸载 hexo-renderer-marked
  • 确保 katex.enable: true 和 per_page: true
  • 检查文章中是否使用了正确的 LaTeX 语法

3.3 部署到 GitHub Pages

  • 确保 _config.yml 中的 deploy 配置正确
  • GitHub Pages 默认分支是 master，注意配置 branch: master

四、常用部署命令

1
2
3
4
5
6
7
# 完整部署流程
hexo clean      # 清除缓存
hexo generate   # 生成静态文件
hexo deploy     # 部署到 GitHub

# 简写
hexo g -d

五、总结

配置 Hexo 博客的关键点：

  1. 搜索功能需要 hexo-generator-searchdb + 主题配置同时开启
  2. LaTeX 渲染需要使用 hexo-renderer-markdown-it-katex 并卸载 hexo-renderer-marked
  3. 部署前记得 hexo clean 清除缓存

希望这篇笔记能帮助到同样在配置 Hexo 博客的你！