KAYOON的个人博客
KAYOON的个人博客

HuGo主题LoveIt的升级版FixIt迁移记录

kayoon 收录于 Hugo
 约 2900 字 预计阅读 6 分钟 - 次阅读  

前几天迁移服务器顺带把博客这块也迁移了，好久没写博客，看着原本LoveIt的主题感觉差点意思，这主题也用了几年了，就想看看有没有更适合的主题。
还别说，在网上找到了这个本文提到的FixIt，页面简洁，还是基于LoveIt的，切换主题难度更小。

1. FixIt介绍

2. 迁移前的准备

2.1 备份现有网站

在进行任何重大更改之前，如果本地没有版本控制，强烈建议你备份整个 Hugo 站点目录。
或者至少确保 content 文件夹和 config.toml(或 config.yaml/config.json) 文件已经用版本控制系统（如 Git）管理起来。这样如果迁移过程中出现意外，你可以轻松回滚到之前的状态。

2.2 升级hugo

本人的hugo是好几年前下载的了，为了确保兼容性，直接升级到较新的版本。

1
2
3
4

# 本人电脑系统是macOS，所以先更新Homebrew
brew update 
# 升级hugo
brew upgrade hugo

2.3 添加 FixIt 主题为子模块

在你的 Hugo 站点根目录下，通过命令行添加 FixIt 主题作为 Git 子模块。

1

git submodule add https://github.com/hugo-fixit/FixIt.git themes/FixIt

这会将 FixIt 主题克隆到你站点根目录（例如我的项目是MySite，那么站点根目录就是MySite，下面同理，就不再多提）的 themes/FixIt 目录下。 使用子模块可以方便地通过 git submodule update --remote --merge 来更新主题到最新版本。

3. 开始迁移

3.1 （重要）替换配置文件

FixIt 主题可能引入了一些新的或者弃用部分配置选项，亦或者对 LoveIt 原有的配置项进行了调整。需要仔细阅读 FixIt 主题的官方文档，对照着检查并修改你的配置文件。
这里强烈建议直接进行以下操作，可以避免很多不必要的麻烦：

  • 备份站点根目录下的config.toml(或 config.yaml/config.json)配置文件，我的是config.toml，名称可以改为config.old.toml。
  • 复制themes/FixIt/hugo.toml到站点跟目录下，并改名为config.toml，然后根据config.old.toml和FixIt文档进行参数配置调整。

3.2 修改配置选项

下面分享下除了原本config.old.toml已经有的内容，我另外修改到的一些操作。

3.2.1 引用FixIt

在config.toml中添加参数theme = "FixIt"进行FixIt主题的引用。

3.2.2 删除layouts自定义模板

删除站点根目录layouts/文件夹下自定义的一些LoveIt模板，或将其迁移到其它位置备份，这个与FixIt会有冲突。

3.2.3 调整友链引用

FixIt的友链引用跟LoveIt有所不同，先在根目录创建友链资源文件data/friends.yml。

1
2
3
4
5
6
7
8
9

# data/friends.yml
- nickname: 好友一号
  avatar: https://via.placeholder.com/100x100.png?text=Avatar1
  url: https://example.com/1
  description: 这是第一位好友的描述。
- nickname: 好友二号
  avatar: https://via.placeholder.com/100x100.png?text=Avatar2
  url: https://example.com/2
  description: 这是第二位好友的描述。

然后再将原本的友链引用

1

{{< friend name="好友A" url="https://a.com" logo="/img/a.jpg" word="描述" >}}

修改为

1

{{< friends >}}

如果感觉友链页面过于简陋，可以直接copy我从网上找到的页面layouts/shortcodes/friends.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
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

{{- /* Friends Shortcode */ -}}
{{- $friends := site.Data.friends -}}
{{- if $friends -}}
<div class="friends-container">
    <h2>🎯 友情链接</h2>
    <div class="friends-grid">
        {{- range $friends -}}
        <a href="{{ .url }}" target="_blank" rel="noopener noreferrer" class="friend-card">
            <div class="friend-avatar">
                <img src="{{ .avatar }}" alt="{{ .nickname }}" loading="lazy" onerror="this.src='/images/default-avatar.png'">
            </div>
            <div class="friend-info">
                <h3 class="friend-name">{{ .nickname }}</h3>
                <p class="friend-desc">{{ .description }}</p>
                <span class="friend-url">{{ .url }}</span>
            </div>
        </a>
        {{- end -}}
    </div>
</div>
{{- else -}}
<div class="friends-empty">
    <p>暂无好友链接，欢迎交换友链！</p>
</div>
{{- end -}}

{{- /* 添加样式 */ -}}
{{- $style := `
.friends-container {
margin: 2rem 0;
padding: 1.5rem;
}

.friends-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(350px, 1fr));
gap: 1.5rem;
margin-top: 1rem;
}

.friend-card {
display: flex;
align-items: center;
padding: 1.5rem;
border: 1px solid #e5e7eb;
border-radius: 12px;
text-decoration: none;
color: inherit;
transition: all 0.3s ease;
background: white;
}

.friend-card:hover {
transform: translateY(-2px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
border-color: #3b82f6;
text-decoration: none;
}

.friend-avatar {
width: 60px;
height: 60px;
border-radius: 50%;
margin-right: 1.2rem;
overflow: hidden;
flex-shrink: 0;
}

.friend-avatar img {
width: 100%;
height: 100%;
object-fit: cover;
}

.friend-info {
flex: 1;
}

.friend-name {
font-size: 1.1rem;
font-weight: 600;
margin: 0 0 0.5rem 0;
color: #1f2937;
}

.friend-desc {
font-size: 0.9rem;
color: #6b7280;
margin: 0 0 0.5rem 0;
line-height: 1.4;
}

.friend-url {
font-size: 0.8rem;
color: #9ca3af;
word-break: break-all;
}

.friends-empty {
text-align: center;
padding: 3rem;
color: #6b7280;
}

@media (max-width: 768px) {
.friends-grid {
grid-template-columns: 1fr;
}

.friend-card {
flex-direction: column;
text-align: center;
}

.friend-avatar {
margin-right: 0;
margin-bottom: 1rem;
}
}
` -}}

<style>{{ $style | safeCSS }}</style>

4. 可能出现的问题

4.1 hugo版本跟FixIt不匹配。

运行hugo serve --buildDrafts时，报错：

1
2

hugo serve --buildDrafts
WARN 2025/09/22 06:59:45 Module "FixIt" is not compatible with this Hugo version; run "hugo mod graph" for more information。

解决方案：升级hugo版本

4.2 Homebrew 环境或软件包异常

MacOS 本地 Homebrew 环境或某个特定软件包（这里是 vagrant）的配置可能出现了问题。

1
2
3
4
5
6

Error: Unexpected method 'bash_completion' called on Cask vagrant.
Follow the instructions here:
  https://github.com/Homebrew/homebrew-cask#reporting-bugs
Error: Unexpected method 'zsh_completion' called on Cask vagrant.
Follow the instructions here:
  https://github.com/Homebrew/homebrew-cask#reporting-bugs

解决方案：升级后再升级hugo

1
2

brew update
brew upgrade hugo

4.3 Busuanzi统计异常

如果有引用Busuanzi作为统计，这个主要表现在文章内容的阅读数统计会归零，原因是更新后的hugo或者FixIt主题生成的页面路径规则跟之前不一致，所以引用Busuanzi单个页面的阅读数统计会从新计算。

4.4 评论模块异常

4.4.1 原本的评论模块不显示

  • 没有开启评论功能
    解决方案：[params.page.comment]中的enable设置为true。
1
2

[params.page.comment]
    enable = true
  • 文章Front Matter的toc被设置为false。
    解决方案：toc设置为true，或者删除掉，会默认继承config.toml中的配置。
1
2
3
4
5
6

---
title: "你的文章标题"
date: 2023-10-27
# toc: false # <- 如果这行存在，请删除或改为 true
categories: ["Web"]
---
  • 对应评论组件没有开启或者配置有误。
    解决方案：没开启就找到对应组件，enable设置为true，已开启根据FixIt文档重新配置一次。

4.4.2 评论模块能显示但没数据

若评论组件用的是giscus，那可能跟Busuanzi统计异常同一个原因，页面路径变更了，无法在GitHub的Discussions中获取到对应的评论，可以自行对比一下或者打开浏览器看看获取评论的链接是不是报404了。

4.5 文章目录导航无法正常显示

可能是没正常开启目录选项。
解决方案：将[params.page.toc]参数中的enable设置为true。

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

[params.page.toc]
      # whether to enable the table of the contents
      enable = true
      # whether to keep the static table of the contents in front of the post
      keepStatic = false
      # whether to make the table of the contents in the sidebar automatically collapsed
      auto = true
      # FixIt 0.2.13 | NEW position of TOC ["left", "right"]
      position = "right"
      # FixIt 0.3.12 | NEW supersede `markup.tableOfContents` settings
      ordered = false
      startLevel = 2
      endLevel = 6
      # FixIt 0.4.0 | NEW whether to decrease the H1 heading level in content
      decreaseH1 = false

4.6 文章列表和样式混乱

可能在 layouts/ 下有自定义模板，或者使用了 LoveIt 的特定 CSS 类。
解决方案：建议直接弃用之前之前写的自定义模板，要不然只能根据错误信息一一修改。

4.7 搜索功能失效

FixIt目前仅支持["algolia", "fuse", "cse", "post-chat"]几种搜索组件。
解决方案：如果之前是用lunr实现搜索功能的，在config.toml中将引用的组件改为fuse，一样是本地索引。

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

# Search config
  [params.search]
    enable = true
    # type of search engine ["algolia", "fuse", "cse", "post-chat"]
    type = "fuse"
    # max index length of the chunked content
    contentLength = 4000
    # placeholder of the search bar
    placeholder = ""
    # max number of results length
    maxResultLength = 10
    # snippet length of the result
    snippetLength = 30
    # HTML tag name of the highlight part in results
    highlightTag = "em"
    # whether to use the absolute URL based on the baseURL in search index
    absoluteURL = false
更新于 2025-09-22 
阅读原始文档
HugoFixIt
返回 | 主页
0%