博客配置更新总结 - 数学公式、永久链接与置顶功能

发表于 更新于 分类于 ， 阅读次数： 本文字数： 2.2k 阅读时长 ≈ 8 分钟

本文总结了近期对博客进行的一系列重要配置更新，包括数学公式渲染支持、永久链接优化、文章置顶功能等，为博客的阅读体验和功能完整性提供了重要提升。

🎯 更新概述

本次更新主要包含四个重要功能：

  1. 数学公式渲染支持 - 解决LaTeX公式显示问题
  2. 永久链接优化 - 使用abbrlink生成简洁稳定的URL
  3. 文章置顶功能 - 重要文章可以置顶显示
  4. Pjax页面加速 - 提升页面切换速度，保持音乐播放连续性

🧮 数学公式渲染支持

问题背景

原有的Markdown渲染器对复杂数学公式支持不够完美，在渲染LaTeX公式时会出现渲染错误，如将 _ 识别为Markdown斜体标识，导致公式渲染失败。

解决方案

采用 hexo-renderer-pandoc 作为新的渲染器，配合 hexo-filter-mathjax 插件完美解决上述问题。

安装步骤

1
2
3
4
5
6
7
8
9
# 安装Pandoc（需要先下载安装）
# 卸载默认渲染器
npm uninstall hexo-renderer-marked --save

# 安装Pandoc渲染器
npm install hexo-renderer-pandoc --save

# 安装MathJax插件
npm install hexo-filter-mathjax --save

配置修改

站点配置文件 (_config.yml)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# MathJax Configuration
mathjax:
  tags: none # or 'ams' or 'all'
  single_dollars: true # enable single dollar signs as in-line math delimiters
  cjk_width: 0.9 # relative CJK char width
  normal_width: 0.6 # relative normal (monospace) width
  append_css: true # add CSS to pages rendered by MathJax
  every_page: false # 如果设置为true,默认每篇文章都会被mathjax渲染

# hexo-renderer-pandoc
pandoc:
  extra:
    - toc: # will be passed as `--toc`
    - --mathjax # 启用MathJax支持
  extensions:
    - "+hard_line_breaks"
    - "+emoji"
    - "-implicit_figures"
    - "+tex_math_dollars" # 支持美元符号数学公式
    - "+tex_math_single_backslash" # 支持单反斜杠
  template: ./pandoc_template.html

主题配置文件 (_config.next.yml)

1
2
3
4
5
6
7
8
math:
  every_page: false
  mathjax:
    enable: true
    tags: none
  katex:
    enable: false
    copy_tex: false

使用方法

在需要数学公式的文章Front-matter中添加：

1
2
3
4
---
title: 你的文章标题
mathjax: true  # 启用数学公式渲染
---

语法示例

1
2
3
4
5
6
行内公式：$E = mc^2$

块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

🔗 永久链接优化

问题背景

由于我们写文章时title可能含有中文，因此会生成含有中文的URL，这会造成许多不可预料的问题。

解决方案

采用 hexo-abbrlink 插件生成简洁、稳定的永久链接。

安装配置

1
npm install hexo-abbrlink --save

站点配置文件 (_config.yml)

1
2
3
4
5
6
permalink: posts/:abbrlink/

# Abbrlink
abbrlink:
  alg: crc32 # 算法： crc16(default) and crc32
  rep: hex   # 进制： dec(default) and hex

效果对比

  • 原来的URL格式：/2025/08/13/博客阅读体验优化与主题自定义指南/
  • 现在的URL格式：/posts/24845/

优势

  • ✅ 解决中文URL编码问题
  • ✅ 链接稳定性，修改标题不影响URL
  • ✅ SEO友好，搜索引擎更喜欢简洁的URL
  • ✅ 便于分享和记忆

📌 文章置顶功能

功能说明

重要文章可以置顶显示在首页顶部，通过设置 top 值控制置顶顺序。

安装配置

1
2
3
4
5
# 移除默认插件
npm uninstall hexo-generator-index --save

# 安装置顶插件
npm install hexo-generator-index-pin-top --save

使用方法

在需要置顶的文章Front-matter中添加：

1
2
3
4
---
title: 你的文章标题
top: 10  # 数值越大，排序越靠前
---

置顶规则

  • top: true 或 top: 1 - 基础置顶
  • top: 10 - 高优先级置顶
  • 数值越大，排序越靠前

当前置顶文章

  1. 博客阅读体验优化与主题自定义指南 - top: 10
  2. GitHub Profile设计 - top: 8
  3. 数学公式渲染测试 - top: 5

🚀 Pjax页面加速

功能说明

Pjax（PushState + Ajax）是一种技术，可以在不刷新整个页面的情况下更新页面内容，从而提升页面切换速度并保持音乐播放的连续性。

主要优势

  • ⚡ 页面切换加速 - 只更新页面内容，不重新加载整个页面
  • 🎵 音乐播放连续性 - 切换页面时音乐不会中断
  • 🎯 更好的用户体验 - 减少页面闪烁，提供更流畅的浏览体验
  • 📱 移动端优化 - 在移动设备上提供更快的响应速度

配置方法

主题配置文件 (_config.next.yml)

1
2
# 启用Pjax
pjax: true

技术实现

Pjax功能由Next主题内置提供，无需额外的JavaScript代码。主题会自动处理：

  • 页面内容的异步加载
  • 浏览器历史记录管理
  • 音乐播放器的状态保持

兼容性说明

  • ✅ 支持所有现代浏览器
  • ✅ 自动降级：如果Pjax失败，会自动回退到普通页面加载
  • ✅ 搜索引擎友好：不影响SEO和页面索引

🎨 侧边栏优化

问题解决

解决了侧边栏中 “StackOverflow” 等长文本显示不全的问题。

解决方案

通过CSS优化解决文字显示不全问题，而不是增加侧边栏宽度：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/* 侧边栏社交链接优化 */
.sidebar .social-links {
  .social-link {
    display: flex !important;
    align-items: center !important;
    justify-content: flex-start !important;
    width: 100% !important;
    min-width: 0 !important;
    
    span {
      flex: 1 !important;
      min-width: 0 !important;
      overflow: hidden !important;
      text-overflow: ellipsis !important;
      white-space: nowrap !important;
      font-size: 0.9em !important;
    }
  }
}

🔧 技术要点总结

渲染器更换

  • 从 hexo-renderer-marked 更换为 hexo-renderer-pandoc
  • 需要安装Pandoc并配置环境变量
  • 支持更复杂的LaTeX语法

插件管理

  • 新增：hexo-filter-mathjax、hexo-abbrlink、hexo-generator-index-pin-top
  • 移除：hexo-generator-index
  • 替换：hexo-renderer-marked → hexo-renderer-pandoc

配置优化

  • 数学公式按需加载，提高页面性能
  • 永久链接使用CRC32算法生成唯一ID
  • 置顶功能支持多级优先级
  • Pjax启用，提升页面切换速度

📊 更新效果

功能完整性

  • ✅ 数学公式完美渲染
  • ✅ 永久链接稳定可靠
  • ✅ 重要文章置顶显示
  • ✅ 侧边栏文字完整显示
  • ✅ Pjax页面加速启用

用户体验

  • ✅ 阅读体验大幅提升
  • ✅ 链接分享更加便捷
  • ✅ 重要内容优先展示
  • ✅ 界面布局更加协调
  • ✅ 页面切换更加流畅
  • ✅ 音乐播放连续不中断

技术稳定性

  • ✅ 兼容性更好
  • ✅ 维护成本降低
  • ✅ SEO优化效果
  • ✅ 性能表现优秀

🚀 后续计划

  1. 数学公式语法统一 - 逐步更新现有文章的LaTeX语法
  2. 性能优化 - 进一步优化页面加载速度
  3. 功能扩展 - 考虑添加更多个性化功能

⚠️ 踩坑记录

置顶功能配置坑爹经历

问题描述：

  • 安装了 hexo-generator-index-pin-top 插件
  • 配置了 top 值来控制文章置顶
  • 结果发现配置过于复杂，影响原有功能

坑爹之处：

  • 插件会覆盖默认的首页生成器
  • 需要同时配置 index_generator 和 archive_generator
  • 配置错误会导致页面无法正常显示
  • 增加了不必要的复杂性

解决方案：

  • 卸载 hexo-generator-index-pin-top
  • 恢复使用默认的 hexo-generator-index
  • 移除所有文章中的 top 配置
  • 保持原有的简单配置

经验教训：

  • 不要盲目安装插件，先了解其影响
  • 保持配置的简洁性
  • 如果功能不是必需的，就不要增加复杂性
  • 备份原始配置很重要！

结论：有时候简单就是最好的！🎯

🔧 Pandoc渲染问题解决

问题背景

在配置Pandoc渲染器后，发现现有文章中的LaTeX语法与Pandoc不兼容，导致大量渲染警告。

主要问题类型

1. 星号语法问题

错误语法：V^*, G^*
正确语法：V^{\ast}, G^{\ast}

原因：Pandoc对LaTeX语法要求更严格，星号需要用 \ast 命令。

2. 上下标语法问题

错误语法：\delta^i_j
正确语法：\delta^{i}_{j}

原因：Pandoc要求上下标必须用大括号包围。

3. 箭头语法问题

错误语法：\xrightarrow{T}
正确语法：\stackrel{T}{\rightarrow}

原因：\xrightarrow 在某些Pandoc版本中不被支持。

修改的文件列表

  1. Duality-and-Isomorphism-1.md

    • 第58行：\delta^i_j → \delta^{i}_{j}
    • 第59行：\delta^i_j → \delta^{i}_{j}

  2. Duality-and-Isomorphism-2.md

    • 第29行：\delta^i_j → \delta^{i}_{j}
    • 第80行：\xrightarrow{T} → \stackrel{T}{\rightarrow}

  3. Duality-and-Isomorphism-4.md

    • 第80行：V^* → V^{\ast}, G^* → G^{\ast}

  4. Math-Formula-Test.md

    • 第95行：\delta^i_j → \delta^{i}_{j}

Pandoc兼容性规则总结

1
2
3
4
5
6
7
8
9
10
11
# 星号语法
V^* → V^{\ast}
G^* → G^{\ast}

# 上下标语法
\delta^i_j → \delta^{i}_{j}
x^2 → x^{2}

# 箭头语法
\xrightarrow{T} → \stackrel{T}{\rightarrow}
\longrightarrow → \rightarrow

经验教训

  • 语法严格性：Pandoc比默认渲染器更严格
  • 逐步迁移：现有文章需要逐步更新语法
  • 测试验证：每次修改后都要测试渲染效果
  • 文档记录：记录修改过程便于后续维护

解决效果

  • ✅ 消除了所有Pandoc渲染警告
  • ✅ 数学公式正确显示
  • ✅ 保持了文章的可读性
  • ✅ 提高了渲染的稳定性

本文记录了博客配置的重要更新，为后续的维护和优化提供了完整的参考文档。

更新时间：2025年8月13日
更新版本：v2.0.0
主要功能：数学公式、永久链接、文章置顶