Hello World — 博客配置说明 | stay hungry stay foolish

本文记录本博客（Hexo + Redefine 主题）的环境、配置与常用操作，方便日后维护。

技术栈

组件	版本 / 说明
Hexo	8.x
主题	Redefine 2.9
Markdown 渲染	`hexo-renderer-markdown-it-plus`
数学公式	`hexo-filter-mathjax`（构建时预渲染为 SVG）
部署	GitHub Pages（`hexo-deployer-git`）

站点地址：https://yuyanqi.com

目录结构（简要）

my-blog/
├── _config.yml              # Hexo 主配置（站点、部署、数学公式）
├── _config.redefine.yml     # Redefine 主题配置
├── source/
│   └── _posts/              # 文章 Markdown
├── scripts/                 # 自定义 Hexo 脚本
│   ├── markdown-it-math-passthrough.js
│   └── mathjax-unwrap.js
├── public/                  # hexo generate 输出（勿手改）
└── package.json

常用命令

# 本地预览
npx hexo server

# 清理缓存并重新生成
npx hexo clean && npx hexo generate

# 部署到 GitHub Pages
npx hexo deploy

一键发布：

1	npx hexo clean && npx hexo generate && npx hexo deploy

站点基础配置（`_config.yml`）

关键项：

# 站点信息
title: 鱿鱼圈的博客
url: https://www.yuyanqi.com
language: zh-CN
theme: redefine

# 文章 URL 格式
permalink: :year/:month/:day/:title/

# 资源与链接
post_asset_folder: true   # 每篇文章可有同名资源文件夹
relative_link: false      # 必须为 false，否则深层页面刷新后 JS/CSS 404

# 部署
deploy:
  type: git
  repo: https://github.com/yyq0210/yyq0210.github.io
  branch: main

relative_link 必须为 false：Redefine 主题开启 Swup 单页导航时，若设为 true，从首页点进文章正常，但直接刷新文章页会导致 js/build/main.js 等脚本路径错误（404），图片 lazyload 失效、控制台报错。

主题配置（`_config.redefine.yml`）

主题独立配置文件，覆盖 _config.yml 中的主题相关项。常用位置：

info：标题、副标题、作者
global.single_page：Swup 单页体验（默认 true）
inject：自定义 head / footer 注入（本博客用于公式样式）

主题文档：https://redefine-docs.ohevan.com

数学公式配置

依赖

1	npm install hexo-filter-mathjax

已移除与 Markdown 冲突的旧渲染器（hexo-renderer-marked、hexo-renderer-kramed），统一使用 hexo-renderer-markdown-it-plus。

`_config.yml` 中的 MathJax

mathjax:
  tags: none
  single_dollars: true      # 支持行内 $...$
  cjk_width: 0.9
  normal_width: 0.6
  append_css: true
  every_page: true
  packages:
    - ams
    - newcommand
    - configmacros

markdown_it_plus:
  breaks: false             # 避免 _ 被当成斜体破坏公式
  plugins:
    - plugin:
        name: '@iktakahiro/markdown-it-katex'
        enable: false       # 关闭 KaTeX，使用 MathJax
    - plugin:
        name: '../../../scripts/markdown-it-math-passthrough'
        enable: true

自定义脚本

1. scripts/markdown-it-math-passthrough.js

在 Markdown 解析阶段保护 $...$ / $$...$$，避免被 emphasis 规则破坏；块级公式输出带换行，防止相邻公式粘成 $$$$。

2. scripts/mathjax-unwrap.js

构建后把 <mjx-container> 替换为 <span class="mathjax-svg">。微信等浏览器不识别 mjx-container 自定义标签，unwrap 后 SVG 可正常显示。

3. _config.redefine.yml → inject.head

注入公式展示 CSS（居中、横向滚动等）。

文章中启用公式

在 front matter 加上：

1	mathjax: true

写作规范

块级公式用 $$...$$，块内不要空行
长推导用 \begin{aligned}...\end{aligned}
下标直接写 _，不要用 \_
中文说明写在 $$ 外面，不要放进公式块
图片与文章同名目录放在 source/_posts/文章名/ 下，正文用 Markdown 图片语法引用 1.png 等文件名（需 post_asset_folder: true）

示例：

$$
S_t = S_{t-1}(\mathbf{I} - \beta_t k_t k_t^\top) + \beta_t v_t k_t^\top
$$

其中 $M_{-1} = M - I$ 表示严格下三角掩码。

新建文章

1	npx hexo new "文章标题"

生成 source/_posts/文章标题.md，按需编辑 front matter 与正文，然后 clean → generate → deploy。

排查清单

现象	可能原因	处理
公式显示 LaTeX 源码	公式被 Markdown 破坏 / 相邻 `$$` 粘连	检查 passthrough 插件；块间留空行
公式不显示（空白）	`mjx-container` 未 unwrap	确认 `mathjax-unwrap.js` 存在并重新 generate
从首页进正常，刷新后图片消失	`relative_link: true`	改为 `false` 并重新部署
部署后仍是旧版	CDN / 浏览器缓存	Ctrl+F5 强制刷新

Hello World — 博客配置说明

技术栈