Jekyll on farmer3-c Blog

博客框架迁移：从 Jekyll 到 Hugo

Sun, 28 Jun 2026 22:00:00 +0800

前言

之前的博客基于 Jekyll + Hux Blog 主题，用了快一年，总觉得不太顺手。Jekyll 是 Ruby 生态，本地构建慢，主题样式偏重（大图背景、多栏布局），对我这种只想简洁写文章的人来说有点臃肿。

于是决定迁移。目标是：

🚀 更快的构建速度
🎨 极简的页面风格 —— 无背景图、干净利落
🔧 少折腾 —— 配置简单，开箱即用
📝 保留所有文章和资源

最终选择了 Hugo + PaperMod 主题。

为什么选 Hugo？

特性	Jekyll	Hugo
语言	Ruby	Go
构建速度	~5-10 秒	~250ms
安装	需 Ruby + Gem	单二进制
配置	`_config.yml`	`hugo.toml`
主题生态	丰富	丰富

Hugo 最大的优势就是快——单二进制文件，没有任何依赖，构建 55 篇文章只要 250ms。PaperMod 主题默认就是白色极简风格，没有大图背景，几乎没有需要改动的地方。

迁移做了什么

1. 文章转换（55 篇）

原来的 Jekyll 文章格式：

1
2
3
4
5
6
7
8
9


---
layout: post
title: "Introduction to Linear Programing"
date: 2025-09-14 23:54:39 +0800
author: "farmer3-c"
header-img: "img/post-bg-2015.jpg"
mathjax: true
tags: []
---

转换为 Hugo 格式：

1
2
3
4
5
6
7


---
title: "Introduction to Linear Programing"
date: "2025-09-14T23:54:39+08:00"
author: "farmer3-c"
mathjax: true
tags: []
---

主要变化：删掉了 layout、header-img 等 Jekyll 特有字段，日期改为 ISO 8601 格式。

2. 资源迁移

img/ → static/img/（路径不变，文章中的图片引用不受影响）
pdf/ → static/pdf/
删除了所有背景大图（*-bg-*.jpg）

3. 功能集成

功能	实现
评论区	Utterances（基于 GitHub Issues）
LaTeX	MathJax 3 支持 $..$ 、`$$..$$`
搜索	PaperMod 内置 Fuse.js
标签	自动标签页 `/tags/`
RSS	自动生成 `/index.xml`
字体	Times New Roman + 宋体
深色模式	自动跟随系统
代码复制	一键复制代码块

新博客使用指南

环境准备

1
2
3
4
5
6


# 安装 Hugo（Windows）
# 从 https://github.com/gohugoio/hugo/releases 下载 hugo_extended 版本
# 解压后添加到 PATH 即可

# 验证安装
hugo version

本地预览

1
2
3
4
5


# 在博客根目录启动服务器
hugo server

# 浏览器访问 http://localhost:1313/
# 修改文件后自动刷新

新建文章

1

hugo new content posts/my-new-post.md

然后在 content/posts/my-new-post.md 中编辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


---
title: "文章标题"
description: "文章摘要"
date: "2026-06-28T23:00:00+08:00"
author: "farmer3-c"
tags:
  - Tag1
  - Tag2
mathjax: true  # 如果用到 LaTeX 则启用
draft: false
---

添加图片

将图片放到 static/img/ 目录下，在文章中引用：

1

![描述](/img/your-image.png)

添加 PDF

将 PDF 放到 static/pdf/ 目录下：

1

[下载文档](/pdf/filename.pdf)

部署

推送到 GitHub 即可自动构建部署：

1
2
3


git add -A
git commit -m "更新"
git push origin main

GitHub Actions 会自动运行 Hugo 构建，将 public/ 目录部署到 GitHub Pages。

文件结构

farmer3-c.github.io/
├── hugo.toml              # 主配置文件
├── content/
│   ├── posts/             # 所有文章
│   ├── about/             # 关于页面
│   └── search.md          # 搜索页
├── static/
│   ├── img/               # 图片资源
│   ├── pdf/               # PDF 文件
│   └── CNAME              # 自定义域名
├── layouts/
│   └── partials/
│       ├── comments.html  # Utterances 评论
│       └── extend_head.html  # MathJax 3
├── assets/
│   └── css/extended/
│       └── custom.css     # 自定义样式
└── .github/workflows/
    └── hugo.yml           # 自动部署

总结

这次迁移大概花了一晚上的时间，最耗时的是 55 篇文章的格式转换和内部链接检查。迁移之后，博客构建速度从秒级降到了毫秒级，主题干净了很多，写文章的体验也好了不少。

希望这篇记录对想从 Jekyll 迁移到 Hugo 的朋友有帮助 😄

博客优化问题与解决方案总结

Sat, 16 May 2026 01:00:00 +0800

博客优化问题与解决方案总结

最近对博客进行了多次优化，遇到了各种问题，现在总结一下遇到的问题及解决方案，供大家参考。

1. Service Worker 自动刷新问题

问题描述

博客添加了 Service Worker 后，每次检测到更新都会显示 “Content updated. REFRESH” 按钮，需要手动点击刷新。

解决方案

修改 js/sw-registration.js，移除手动刷新提示，直接使用 location.reload()。

1
2
3
4
5


if(data.command == "UPDATE_FOUND"){
  console.log("UPDATE_FOUND_BY_SW", data);
  // 自动刷新页面，无需手动点击
  location.reload();
}

后续问题

启用自动刷新后，网站出现了无限刷新循环的问题，用户体验极差。

最终解决方案

移除 Service Worker 的自动刷新机制，改用 Stale-While-Revalidate 缓存策略：

优先显示缓存内容
后台更新缓存
用户下次访问时自然看到新内容

2. 导航栏显示文章标题问题

问题描述

导航栏突然显示了文章标题 “编译实践Lv1. main 函数”，而不是正常的页面链接。

根本原因

之前误将一篇博客文章放到了 css/ 文件夹，Jekyll 将其当作页面处理，导致导航栏循环显示所有有 title 的页面。

解决方案

彻底解决方案： 硬编码导航栏，只显示固定页面。

修改 _includes/nav.html：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<ul class="nav navbar-nav navbar-right">
  <li>
    <a href="{{ site.baseurl }}/">Homea>
  li>
  <li>
    <a href="{{ site.baseurl }}/about/">Abouta>
  li>
  <li>
    <a href="{{ site.baseurl }}/archive/">Archivea>
  li>
  <li class="search-icon">
    <a href="javascript:void(0)">
      <i class="fa fa-search">i>
    a>
  li>
ul>

同时从 git 历史中彻底移除误放的文章。

3. About 和 Archive 页面 404 问题

问题描述

点击导航栏的 About 和 Archive，跳转到 /about.html 和 /archive.html，显示 404 错误。

原因

博客使用了 permalink: pretty 配置，正确的 URL 应该是 /about/ 和 /archive/（带斜杠），而不是 .html 结尾。

解决方案

修改导航栏链接格式：

1
2
3
4
5
6
7



<a href="{{ site.baseurl }}/about.html">Abouta>
<a href="{{ site.baseurl }}/archive.html">Archivea>


<a href="{{ site.baseurl }}/about/">Abouta>
<a href="{{ site.baseurl }}/archive/">Archivea>

4. GitHub Pages 构建队列卡住问题

问题描述

推送代码后，GitHub Actions 一直显示 “Queued” 状态，超过 10 分钟甚至更久都没有构建。

原因分析

这是 GitHub 服务本身的问题，不是代码问题。根据 GitHub Status 页面显示，GitHub Actions 服务正在经历事故（Incident）。

解决方案

等待 GitHub 修复
- 通常需要 30 分钟到几小时
- 关注 https://www.githubstatus.com/ 获取最新状态
检查 GitHub 服务状态
- GitHub Status: https://www.githubstatus.com/
- Twitter: @githubstatus
- Downdetector: downdetector.com/status/github
本地验证代码正常
1

bundle exec jekyll build
如果本地构建成功，说明代码没问题，只是 GitHub 服务问题。

预防措施

推送代码前先在本地预览
避免在 GitHub 服务不稳定时推送重要更新

5. 新文章推送后不显示问题

问题描述

新写的文章 git push 之后在博客网站没有显示。

常见原因

文件名格式问题
- 要求：YYYY-MM-DD-title.md
- 避免在文件名末尾使用特殊字符

Front Matter 格式问题

1
2
3
4
5
6


---
layout: post
title: "文章标题"
date: 2026-03-06
tags: [Tag1, Tag2]  # 标签用逗号分隔，不要有空格
---

标签格式问题

1
2
3
4
5
6
7


# 错误：包含空格的标签
tags: [Algorithm programming problem]

# 正确：逗号分隔或加引号
tags: [Algorithm, programming, problem]
# 或
tags: ["Algorithm programming problem"]

解决方案

确保文件名格式正确
检查 front matter 格式
修复后重新提交推送

6. LaTeX 数学公式渲染失败问题

问题描述

博客中的 LaTeX 代码显示为纯文本 [Math Processing Error]，无法正常渲染。

解决方案

更新 MathJax 配置到稳定版本。

修改 _includes/mathjax_support.html：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [ ['$','$'], ['\\(','\\)'] ],
      displayMath: [ ['$$','$$'], ['\\[','\\]'] ],
      processEscapes: true
    },
    TeX: {
      equationNumbers: { autoNumber: "AMS" },
      extensions: ["AMSmath.js","AMSsymbols.js"]
    },
    "HTML-CSS": {
      scale: 100
    }
  });
script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS_HTML">script>

使用方法

确保文章头部开启了 mathjax：

1
2
3


---
mathjax: true
---

支持的语法：

类型	语法	示例
行内公式	$...$	$E=mc^2$
行间公式	`$$...$$`	$$\int_0^1 x^2 dx$$
括号公式	`\[...\]`	\[a^2 + b^2 = c^2\]

7. 添加相关文章侧边栏功能

功能描述

在文章页面左侧显示同标签的其他文章列表，方便读者浏览相关内容。

解决方案

创建 _includes/related-posts.html

 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


{% if page.tags.size > 0 %}
<div class="related-posts">
    <hr class="hidden-sm hidden-xs" style="margin: 0 0 20px 0;">
    <h5 style="color: #333; margin-bottom: 15px; font-size: 14px; font-weight: bold;">相关文章h5>
    <ul class="related-posts-list">
        {% assign current_url = page.url %}
        {% assign tag_posts = "" | split: "" %}

        {% for tag in page.tags %}
            {% for post in site.tags[tag] %}
                {% unless post.url == current_url %}
                    {% unless tag_posts contains post %}
                        {% assign tag_posts = tag_posts | push: post %}
                    {% endunless %}
                {% endunless %}
            {% endfor %}
        {% endfor %}

        {% for post in tag_posts limit: 10 %}
        <li>
            <a href="{{ post.url | prepend: site.baseurl }}">
                {{ post.title | truncate: 28 }}
            a>
        li>
        {% endfor %}
    ul>
div>
{% endif %}

修改 _layouts/post.html，在左侧添加：

1
2
3
4



<div class="col-lg-2 visible-lg-block sidebar-container">
    {% include related-posts.html %}
div>

总结

问题	状态	解决方案
自动刷新	✅ 已解决	移除自动刷新，改用自然更新
导航栏异常	✅ 已解决	硬编码导航栏
页面 404	✅ 已解决	修复链接格式
GitHub 构建卡住	⏳ 等待恢复	等待 GitHub 服务修复
文章不显示	✅ 已解决	修复文件名和标签格式
LaTeX 渲染失败	✅ 已解决	更新 MathJax 配置
相关文章功能	✅ 已实现	添加侧边栏组件

经验教训

本地预览很重要 - 推送前先在本地测试
GitHub 服务也会出问题 - 遇到问题先检查服务状态
文件名和格式要规范 - 遵循 Jekyll 的命名规则
做好备份 - 重要修改前先 commit

本文持续更新中…