博客升级 Hugo 与主题 Even

介绍

距离上次切换到 Hugo 主题 Even - 狂飙已经过去两年了，使用的 Even 主题也没有什么大问题，一些想要的改动自己也就定制了。

但是最近突然发现 Even 主题的 diff 代码语法高亮有问题，全是一个颜色，无法区分出哪变化的部分。另外 Even 新版本不再使用 webpack 工具链而是改用 Hugo Pipes 来修改样式表，所以后续修改样式表更容易了。

重要: 本主题用到了 Hugo Pipes 功能。如需修改 assets 目录下的文件，请安装 extended 版。

原则

博客最重要的不是主题，而是内容。必须保证内容链接的有效性，因此要检查升级后生成的目录结构与升级前是否完全一致。

一定要负责任，放到互联网上的东西，没人希望链接突然失效，因此我们应该尽可能地保证自己的东西都是稳定可用的。

环境

macOS 10.14.6

版本变化

版本变化	旧版本	新版本
Hugo	v0.54.0	v0.84.0
Even 主题	v4.0.0	v4.1.0

结果比较方法

在开始前先明确验证输出内容是否相同的方法。

构建概要比较

比较新旧版本 Hugo 构建之后的概要输出，比较结果看看是否有差异。

目录结构比较

使用 Beyond Compare 比较新旧版本的目录结构，在 规则 中取消勾选 比较文件大小 与 比较时间戳，这样可以只比较文件名。

过程

Hugo

Hugo 下载指定版本，hugo_0.84.0_macOS-64bit.tar.gz，暂时解压到临时目录使用，不替换现有安装的版本。

Releases · gohugoio/hugo

Even 主题

主题是使用子仓库的形式管理，因此可以将改动放到单独的网站分支上。

1
2
3
4


$ git fetch upstream
$ git branch --move networm.me networm.me_hugo-v0.54.0_even-v4.0.0
$ git checkout -b networm.me_hugo-v0.84.0_even-v4.1.0
$ git rebase v4.1.0

构建网站

更新到新版本需要将自定义的改动变基到最新版本，在处理冲突后同步使用新版本 Hugo 构建，查看是否存在异常。

由于自定义修改了主页显示方式为存档，使用了旧版本的语法，因此构建时报错：

1
2
3
4


$ ~/Downloads/hugo_0.84.0_macOS-64bit/hugo server
Start building sites …
Built in 281 ms
Error: Error building site: failed to render pages: render of "home" failed: "~/networm.me/themes/even/layouts/index.html:2:29": execute of template failed: template: index.html:2:29: executing "content" at <(where .Site.RegularPages "Type" "post") .Site.RegularPages.ByDate.Reverse>: can't give argument to non-function where .Site.RegularPages "Type" "post"

修复方法：

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


diff --git a/layouts/index.html b/layouts/index.html
index de0dba7..f20c32c 100644
--- a/layouts/index.html
+++ b/layouts/index.html
@@ -1,10 +1,10 @@
 {{- define "content" }}
-{{- $paginator := .Paginate ((where .Site.RegularPages "Type" "post") .Site.RegularPages.ByDate.Reverse) .Site.Params.archivePaginate }}
+{{- $paginator := .Paginate ((where .Site.RegularPages "Type" "post").ByDate.Reverse) .Site.Params.archivePaginate }}
 <section id="archive" class="archive">
   {{- if and (not $paginator.HasPrev) .Site.Params.showArchiveCount }}
   <div class="archive-title">
     <span class="archive-post-counter">
-      {{ T "archiveCounter" (len .Site.RegularPages) }}
+      {{ T "archiveCounter" (len (where .Site.RegularPages  "Type" "post")) }}
     </span>
   </div>
   {{- end -}}

alias 修复

在进行结果比较时，发现新版本 Hugo 会将 alias 生成到 url 相同的路径下，例如

就会将 find-merge-conflict-files.html 生成到 /2014/05/07/ 目录下。

修复起来也很简单，只需要在首部增加 / 表示绝对路径即可。

1
2
3
4
5


 ---
 aliases:
-  - find-merge-conflict-files.html
+  - /find-merge-conflict-files.html
 url: /2014/05/07/find-merge-conflict-files/

在 Visual Studio Code 中使用正则表达式进行批量文件查找替换：aliases:\n - ([^/]) 替换为 aliases:\n - /$1，这里注意查找时使用了 [^/] 来防止替换到以 / 开头的正确 alias。

编译警告

1

WARN 2021/06/12 22:34:09 Page.URL is deprecated and will be removed in a future release. Use .Permalink or .RelPermalink. If what you want is the front matter URL value, use .Params.url

全局搜索 .URL 然后一点一点替换，找到产生问题的地方。经过实际查找替换，只有两个文件存在问题。

 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


diff --git a/layouts/index.html b/layouts/index.html
index f20c32c..f1f242f 100644
--- a/layouts/index.html
+++ b/layouts/index.html
@@ -23,7 +23,7 @@
       {{ $element.Date.Format "2006-01-02 Mon" }}
     </span>
     <span class="archive-post-title">
-      <a href="{{ $element.URL }}" class="archive-post-link">
+      <a href="{{ $element.Permalink }}" class="archive-post-link">
         {{ .Title }}
       </a>
     </span>
diff --git a/layouts/share/single.html b/layouts/share/single.html
index fcda0dd..54e95e9 100644
--- a/layouts/share/single.html
+++ b/layouts/share/single.html
@@ -53,14 +53,14 @@
       <!-- Post Pagination -->
       <nav class="post-nav">
         {{ with .NextInSection -}}
-          <a class="prev" href="{{ .URL }}">
+          <a class="prev" href="{{ .Permalink }}">
             <i class="iconfont icon-left"></i>
             <span class="prev-text nav-default">{{ .Title }}</span>
             <span class="prev-text nav-mobile">{{ T "prevPost" }}</span>
           </a>
         {{- end }}
         {{ with .PrevInSection -}}
-          <a class="next" href="{{ .URL }}">
+          <a class="next" href="{{ .Permalink }}">
             <span class="next-text nav-default">{{ .Title }}</span>
             <span class="next-text nav-mobile">{{ T "nextPost" }}</span>
             <i class="iconfont icon-right"></i>

结果比较

上面的每一步都需要进行结果比较，尽可能早地发现问题。

所有提交处理后，再次进行比较，目录结构没有差异，但是概要显示页面数量减少了 2 页。既然最终生成的目录结构完全一致，就不去查找为什么页面数量差 2 页了。

结果

打开现在的博客的源代码，即可以看到如下字样，证明升级成功：

1

<meta name="generator" content="Hugo 0.84.0 with theme even">

已经将修改结果提交到 Fork 后的仓库 networm.me_hugo-v0.84.0_even-v4.1.0 默认分支中：

networm/hugo-theme-even

之前的旧版本放在 networm.me_hugo-v0.54.0_even-v4.0.0 分支中。

文章目录

介绍

原则

环境