Hugo on 叶寻的博客

优化 Hugo 博客速度：Pjax、dynamic script、preload、minification

Fri, 18 Oct 2024 00:00:00 +0800

本文介绍了优化博客速度的几个方式：Pjax（免刷新加载页面）、dynamic script（动态插入脚本）、rel=preload（预加载）、minification（极简化）。

本博客是 Hugo 生成的静态网站，感觉访问速度还不算慢。有天我看别人的博客（大概是单页应用），发现点击链接居然没刷新网页就加载了新页面，速度非常快。那时我想：要是我的 Hugo 博客也能这么流畅就好了。我感觉把博客改成单页应用要耗费不少时间，遂作罢。

后来我发现可以用 Pjax 技术让静态网站实现免刷新加载页面。Pjax 的意思是 pushState（修改 URL）+ Ajax（asynchronous JavaScript and XML，发送请求）。通俗来说，Pjax 就是请求网页、替换内容、修改 URL，这个过程比加载整个页面更快。

搜索 Pjax 库，找到两个好几年没更新的库（MoOx/pjax、defunkt/jquery-pjax），我不想用不维护的库。我快放弃的时候发现了一个支持 Pjax 的 Hugo 主题：hugo-theme-luna，从自述文件可以看出 Pjax 是用 swup 实现的，然后我就用它了。

Pjax 免刷新加载页面 #

如果网站没有 JavaScript 代码，那直接加载 swup 就好了。

建议使用这些插件：

Head Plugin：刷新 <head> 元素的内容和 <html> 元素的 lang 属性。
Preload Plugin：光标在链接时预加载 URL，用户点击时就会内容会马上替换，还可以配置自动加载出现在可见区域的链接。
Progress Bar Plugin：加载时间较长时显示进度条。

注意要先加载插件再加载 swup。

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


<script src="https://unpkg.com/@swup/head-plugin@2"></script>
<script src="https://unpkg.com/@swup/preload-plugin@3"></script>
<script src="https://unpkg.com/@swup/progress-plugin@3"></script>
<script src="https://unpkg.com/swup@4"></script>

<script>
 const swup = new Swup({
 containers: ["body"], // 替换 <body> 的内容
 plugins: [
 new SwupHeadPlugin(),
 new SwupPreloadPlugin({ preloadVisibleLinks: true }), // 预加载页面可见的链接
 new SwupProgressPlugin(),
 ],
 });
</script>

我的博客用到了 3 个 JavaScript 程序：Google Analytics（流量统计）、Giscus（评论服务）、Disqus（评论服务），用了 swup 之后要考虑是否需要额外处理。

读者点击链接加载新页面后的处理：

Google Analytics：参考 Measure single-page applications | Google Analytics | Google for Developers，打开 Enhanced measurement 就可以检测页面变化了。
Giscus：加载。
Disqus：重置（reset）或者加载。

Dynamic Script 动态插入脚本 #

我写了个动态插入脚本的函数，可以设置等待时间、加载前执行的函数、async、加载后执行的函数、attribute。

 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


function loadScript({
 url,
 delay,
 onloadCallback,
 async,
 preloadCallback,
 attributes = {},
}) {
 function load() {
 if (preloadCallback) preloadCallback();

 const script = document.createElement("script");
 script.src = url;
 script.async = async;

 // Set attributes
 Object.entries(attributes).forEach(([key, value]) => {
 script.setAttribute(key, value);
 });

 if (onloadCallback) script.onload = onloadCallback;

 document.body.appendChild(script);
 }

 if (typeof delay !== "undefined") {
 setTimeout(load, delay);
 } else {
 load();
 }
}

我给 Google Analytics、Giscus、Disqus 加了 100ms 等待时间，给 swup 添加了 200ms 等待时间。

rel=preload 预加载 #

在 <link> 标签使用 rel="preload" 可以让浏览器提前下载资源（字体、图片、脚本、样式等），后面动态插入脚本时浏览器就可以马上执行下载好的脚本。

示例：

1
2
3
4
5


<head>
 <link rel="preload" as="script" href="https://unpkg.com/@swup/head-plugin@2">
 <link rel="preload" as="script" href="https://unpkg.com/@swup/preload-plugin@3">
 <link rel="preload" as="script" href="https://unpkg.com/swup@4">
</head>

preload 应该叫 predownload，因为它并不会提前加载脚本，只是提前下载。

Minification 极简化 #

这次优化博客没用到极简化，不过既然讲到优化博客了，就顺便说一下吧。极简化就是移除代码中不必要的内容（比如：空格、空行、缩进），从而减小文件大小，这样浏览器就能更快下载完网页。

Hugo 可以极简化 HTML、CSS 和 JavaScript 文件。本博客的代码用 Hugo 极简化了。举个例子，样式文件大小原本是 13.8 kB，经过极简化后是 7.4 kB（原文件的 53.6%），传输过程中再经过 Brotli 压缩后是 2.1 kB（原文件的 15.2%）。

感想 #

我已经用 swup 两三天了，非常满意，真没想到静态网站可以变成单页应用。Preload 插件能让浏览器会自动提前加载页面，读者点击链接时页面会瞬间加载，这个感觉太爽啦！

参考资料 #

2024-08-03 本站改动：使用 Yue 主题和 giscus 评论，post 目录改为 posts

Sat, 03 Aug 2024 00:00:00 +0800

本文列举了本站于2024年7月28日至2024年08月03日的改动。

清理无用文件
使用我写的 Yue 主题（感觉自己从几乎不折腾博客一下走到折腾博客的尽头了，用自己的主题太爽了，哈哈）
讲 utterances 评论服务改为 giscus（终于可以回复评论了，不需要引用文字或者 @）
将 post 文件夹改为 posts

改动很多，最好在 Git 仓库建一个分支搭配子域名（如 test.cyrusyip.org）测试，没问题再合并代码至主分支。修改网站要注意功能和链接（URL）变动，改了链接要修改文章内部链接、重定向、迁移评论。

清理无用文件 #

不再使用以下软件/服务：

blogdown
Netlify
Vercel
……

删除相关文件，修订自述文件和 package.json。

将主题换为 Yue #

先构建一次，保存起来

1
2
3
4


cd cyrusyip-blog
mkdir ~/Desktop/blog-builds
rm -r public; npx hugo # hugo 前面多了 npx 是因为我用 npm 安装 hugo
mv public ~/Desktop/blog-builds/jane

删除 Jane 主题和相关文件，重命名配置和中文内容文件夹。

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


# 删除相关文件
rm -r assets layouts resources
git add --all
git commit --message 'chore: remove custom files related to jane theme'
# 删除主题
git submodule deinit themes/jane # 修改 .git/config
git rm themes/jane # 修改 .gitmodules
rm -rf .git/modules/themes/jane # 删除本地文件
git commit --message 'feat!: remove jane theme'
# 重命名
mv config.toml _config.toml
mv content/zh-cn content/zh-CN
git add --all
git commit --message 'refactor: rename to content/zh-CN and _config.toml'

安装主题。

1
2


git submodule add --depth=1 https://github.com/CyrusYip/hugo-theme-yue themes/hugo-theme-yue
git commit --message 'feat: add hugo-theme-yue'

写新配置，对照原来的配置（_config.toml）。删掉了 keywords、description、Google Analytics、Disqus、utterances，后面再加回来。

1
2
3


cp themes/hugo-theme-yue/exampleSite/hugo.yaml .
# 写好新配置后删除旧配置
rm _config.toml

构建，对比目录名和文件名变化，如果没变化表示 URL（链接）没变化。用 tree 命令列举两次构建的文件，复制到剪切板，使用 Diffchecker 对比。

1
2
3
4
5


rm -r public; npx hugo
# 旧主题
tree ~/Desktop/blog-builds/jane | wl-copy
# 新主题
tree ~/Desktop/blog-builds/yue | wl-copy

新主题编译的网站少了一些没用到的页码，这里无需处理。新网站还多了一篇 2021-01-29-python-calculate-utility-bills.Rmarkdown，这是 Rmarkdown 文件，不应该出现于此，在配置文件忽略它。

1
2


# hugo.yaml
ignoreFiles: ["\\.Rmd$", "\\.Rmarkdown$", "_cache$", "\\.knit\\.md$", "\\.utf8\\.md$"]

构建网站后再对比，没这个 .Rmarkdown 文件了。

对比：

原主题编译的网站有 607 个目录，480 个文件，构建时间 750ms。
新主题编译的网站有 398 个目录，354 个文件，构建时间 450ms。新网站关闭了 enableGitInfo，还没添加统计和评论功能（只是加脚本应该不太会影响构建时间）。

用肉眼对比新旧网站，看看有没有问题。看样式、文章数量、日期等。

添加本站原有的功能 #

Google Analytics
utterances
Disqus
- 只在 cyrusyip.org 上面显示
- 这次加上了多语言功能
图片说明文字
页脚
- 社交媒体、~~Github、Stack overflow、Twitter~~
- CC BY-NC-SA 4.0 协议
meta description
~~keywords~~（meta keywords 已过时，参看 Meta Keywords：是什么、为什么不 | Sukka’s Blog）

将 utterances 评论改为 giscus #

另建一个站点测试会比较稳妥，但这次为了节约时间就直接改了。

giscus 由 GitHub Discussions 驱动，功能比 utterances 强，支持多语言和回复评论。

转换步骤：

删除网站的 utterances
给相关 issue 打标签「Comments」，issue 不多我就直接在网页操作了，一次可以改一页，多的话用 gh issue edit 命令
开启 Discussion，新建类别「Comments」
测试 giscus 是否能新建讨论，标题是否正确
转换 issue（Comments 标签）为 discussion（ Comments 类别），参看 Managing discussions - GitHub Docs#converting-issues-based-on-labels。页面显示「Open issues with label ‘Comments’ are being converted to discussions」，但是过了一两个小时都没反应，最后手动转换了。
创建 giscus.json 配置文件，限制域名，参看 giscus/ADVANCED-USAGE.md#origins
在 GitHub 卸载 utterances
把仓库名 blog-comment 改为 blog-comments，去 giscus 官网重新获取脚本（非必须步骤，这里存了超过一则评论，所以用复数 comments）

post 文件夹改为 posts #

之前用的 Even 主题和 Jane 主题要求内容放在 content/post 文件夹，但是标签（/tags/）和类别（/categories/）用的是复数，我觉得这非常不协调。这次换主题终于可以改成复数 posts 了。

改了之后网站链接（URL）会变化，需要重定向旧链接、修改文章内链接、迁移评论，参考我之前写的文章（真是帮了大忙）：

重命名文件夹 #

构建未修改的网站并保存。

1
2
3


cd cyrusyip-blog
rm -r public; npx hugo
mv public ~/Desktop/blog-builds/before

重命名文件夹。

1
2


mv content/en/post content/en/posts
mv content/zh-CN/post content/zh-CN/posts

预览并修改配置。

1

rm -r public; npx hugo server --navigateToChanged --bind 0.0.0.0

1
2
3
4
5
6
7
8


--- a/hugo.yaml
+++ b/hugo.yaml

- post: /post/:year/:month/:day/:slug/
+ posts: /posts/:year/:month/:day/:slug/

- pageRef: /post
+ pageRef: /posts

1
2
3
4
5
6
7
8


--- a/frontmatter.json
+++ b/frontmatter.json

- "path": "[[workspace]]/content/en/post",
+ "path": "[[workspace]]/content/en/posts",

- "path": "[[workspace]]/content/zh-CN/post",
+ "path": "[[workspace]]/content/zh-CN/posts",

1
2


git add --all
git commit --message "refactor: content/*/post -> content/*/posts"

关掉 Hugo 服务器，构建修改后的网站并保存。

1
2


rm -r public; npx hugo
mv public ~/Desktop/blog-builds/after

复制两个网站目录的结构到剪切板，用 Diffchecker 对比。

1
2
3
4


# 旧网站，Original text
tree ~/Desktop/blog-builds/before | wl-copy
# 新网站，Changed text
tree ~/Desktop/blog-builds/after | wl-copy

就只是 post 目录变成了 posts。

1
2
3
4
5


- /en/post
+ /en/posts

- /zh-cn/post
+ /zh-cn/posts

修改文章内部链接 #

要将 [本站的某文章](/zh-cn/post/2021/01/01/hi/) 这样的链接改成 [本站的某文章](/zh-cn/posts/2021/01/01/hi/)。获取包含链接的文件，并删掉不需要改的链接。

1
2
3


mkdir todo
rg '\[.*\]\(/.*\)' content --only-matching >> todo/internal-links
rg 'cyrusyip\.org' content >> todo/internal-links

链接记录节选：

1
2
3


content/zh-CN/posts/2021-06-19-ac2100-openwrt.md:[红米 AC2100 刷 breed 后刷回官方固件](/zh-cn/post/2022/10/16/ac2100-stock-firmware/)
content/zh-CN/posts/2021-08-30-raspberry-pi-4b-openwrt.md:[在 OpenWrt 控制树莓派 Argon Mini Fan](/zh-cn/post/2021/09/15/openwrt-argon-mini-fan/)
content/zh-CN/posts/2021-08-30-raspberry-pi-4b-openwrt.md:[树莓派 4B 超频教程](/zh-cn/post/2021/09/20/raspberry-pi4-overclock/)

自己手动改链接，改一条就删去一条记录。使用 hugo server --navigateToChanged 命令预览网站可以很方便地查看变化。

我一开始让 ChatGPT 写 Node.js 脚本帮我改，多番交流后它生成了一些不存在的链接，看来这个工作还是太难为它。

重定向 #

现在本站使用 Cloudflare Pages 构建，参考 Redirects · Cloudflare Pages docs 设置重定向。我有点搞不懂我之前写的一些重定向规则，所以要写好注释，未来的我会感谢现在写注释的我。

1
2
3
4
5
6
7


# static/_redirect
######################################################################
# Rename "content/{en,zh-CN}/post" to "content/{en,zh-CN}/posts"
# URL changes: /en/post/ -> /en/posts/ , /zh-cn/post/ -> /zh-cn/posts/
######################################################################
/en/post/* /en/posts/:splat 308
/zh-cn/post/* /zh-cn/posts/:splat 308

测试链接：

关闭评论 #

关闭 Disqus 和 giscus 评论，以免迁移时有读者留言。

迁移 Disqus 评论 #

参考教程：How to download, edit, and upload a URL Map CSV | Disqus

打开迁移工具，点击「Start URL mapper」->「you can download a CSV here」，去邮箱拿到下载链接，下载并解压。这个 CSV 里面的链接非常乱，有无评论的、带查询参数的（/?utterances=xxx）、失效链接。建一个 Git 仓库，把 CSV 文件放进去并提交，后面方便看改动。

修改 CSV，留下以 https://cyrusyip.org/zh-cn/post 和 https://cyrusyip.org/en/post 开头的。

文件节选：

1
2


https://cyrusyip.org/zh-cn/post/2021/03/08/girls-day-womens-day-and-goddesses-day/
https://cyrusyip.org/zh-cn/post/2021/01/10/remove-odor/

在 Vim 执行 :%s/.*/&,&，现在每行都有两个一样的链接，提交改动。

1
2


https://cyrusyip.org/zh-cn/post/2021/03/08/girls-day-womens-day-and-goddesses-day/,https://cyrusyip.org/zh-cn/post/2021/03/08/girls-day-womens-day-and-goddesses-day/
https://cyrusyip.org/zh-cn/post/2021/01/10/remove-odor/,https://cyrusyip.org/zh-cn/post/2021/01/10/remove-odor/

执行 :%s/\v(.*)(post)/\1posts，现在把每行第二个链接的 post 改成 posts，提交改动。

1
2


https://cyrusyip.org/zh-cn/post/2021/03/08/girls-day-womens-day-and-goddesses-day/,https://cyrusyip.org/zh-cn/posts/2021/03/08/girls-day-womens-day-and-goddesses-day/
https://cyrusyip.org/zh-cn/post/2021/01/10/remove-odor/,https://cyrusyip.org/zh-cn/posts/2021/01/10/remove-odor/

把修改后的 CSV 文件上传到 Disqus 的 URL mapper。

迁移 giscus 评论 #

将标题的 post 改为 posts。

示例：

1
2


- zh-cn/post/2024/04/05/i-hate-obscure-words/
+ zh-cn/posts/2024/04/05/i-hate-obscure-words/

GitHub CLI 不支持修改 Discussion，又得手动改了。

查看评论 #

这几篇文章有 Disqus 评论，打开看看是否有评论。

在 Discussions 里找几篇文章，打开看看是否有评论。

开启评论 #

可以看到评论，重新打开 Disqus 和 giscus。

Hugo：自定义标签标题

Tue, 09 Jul 2024 00:00:00 +0800

背景 #

一开始我用 Hugo 做中文网站时打算在文章里用中文标签，但是链接里面的中文会被转换为人类读不懂的字符。比如：/zh-cn/tags/博客/ 会变成 /zh-cn/tags/%E5%8D%9A%E5%AE%A2/。我不喜欢这样，当时搜索一番也没找到办法，就用英文标签了。现在终于知道怎么改了，最终改为链接里面还是用英文，但是页面就显示中文。

下面是针对 hugo-theme-jane（ef8a126）主题的更改方法，方法是通用的，但是不同主题修改的部分可能不同。开始前先厘清两个概念：标签名（tag name）、标签标题（tag title）。在文章前页（front matter）写的是标签名，用于链接；在 _index.md 文件定义的是 title 是标签标题，它会显示于页面。

1
2
3
4
5
6


---
# /content/zh-cn/post/2021-03-21-dongman.md
title: 动漫这个词不能再用了
tags:
 - anime # 标签名
---

1
2
3
4


---
# /content/zh-cn/tags/anime/_index.md
title: 日本动画 # 标签标题
---

如果你启用了 GitInfo 而且不想更改 lastmod，请参考 Hugo：给文章添加 lastmod（上次修改时间）。

修改标签单页标题（`/zh-cn/tags/*/`） #

以 anime（日本动画）为例。先自定义一个标签的标题。

1
2


mkdir --parents content/zh-cn/tags/anime/
touch content/zh-cn/tags/anime/_index.md

添加内容：

1
2
3
4


---
# /content/zh-cn/tags/anime/_index.md
title: 日本动画
---

文章前页（front matter）的 tags 还是保持用 anime。

1
2
3
4
5
6


---
# /content/zh-cn/post/2021-03-21-dongman.md
title: 动漫这个词不能再用了
tags:
 - anime
---

现在 /zh-cn/tags/anime/ 会显示「日本动画」。

修改文章底下的标签标题（`/zh-cn/post/*`） #

在浏览器 inspect 找到 CSS 类，然后去 VS Code 搜索。

本地预览网站。随便打开一篇文章（http://localhost:1313/zh-cn/post/2022/12/03/ajin-oad/），滚动到底部的标签，右击 Inspect，可以看到对于的 HTML 代码。

1
2
3


<div class="post-tags">
 <a href="http://localhost:1313/zh-cn/tags/anime/">anime</a>
</div>

搜索主题目录。

1

rg '<div class="post-tags">' themes/jane

可以发现此代码就在 themes/jane/layouts/post/single.html，将其复制到 layouts/post/（我之前复制过，这次跳过此步骤）。

编辑 layouts/post/single.html。

找到下面这段代码：

1
2
3
4
5
6
7
8


<div class="post-tags">
 {{ range . }}
 {{- $name := . -}}
 {{- with $.Site.GetPage "taxonomy" (printf "tags/%s" $name) | default ($.Site.GetPage "taxonomy" (printf "tags/%s" ($name | urlize))) -}}
 <a href="{{ .Permalink }}">{{ $name }}</a>
 {{ end -}}
 {{ end }}
</div>

将 <a href="{{ .Permalink }}">{{ $name }}</a> 里面的 $name 改为 .LinkTitle。改完是这样的：

1

<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>

现在 http://localhost:1313/zh-cn/post/2021/03/21/dongman/ 底下会显示标签「日本动画」。

修改标签列表页面（`/zh-cn/tags/`） #

用前面的方法 Inspect 元素并搜索代码。

1

rg '<div class="tag-cloud-tags">' themes/jane

可以发现标签列表页面的模板为 themes/jane/layouts/_default/terms.html，复制一份到根目录再改。

1
2
3
4


mkdir --parents layouts/_default/
cp themes/jane/layouts/_default/terms.html layouts/_default/
git add layouts/_default/terms.html
git commit --message 'chore: copy layouts/_default/terms.html'

打开 layouts/_default/terms.html，搜索 tag-cloud-tags，找到这段代码。

1
2
3
4
5
6


<div class="tag-cloud-tags">
...
 <a href="{{ .Permalink }}"
 style="font-size:{{$currentFontSize}}{{$fontUnit}}">{{ $tagName }}</a>
...
</div>

将里面的 $tagName 改为 .LinkTitle：

1
2


<a href="{{ .Permalink }}"
 style="font-size:{{$currentFontSize}}{{$fontUnit}}">{{ .LinkTitle }}</a>

提交改动。

1
2


git add layouts/_default/terms.html layouts/post/single.html
git commit --message 'feat: use tag title'

修改所有标签名，加上标签标题 #

标签名全部改成全小写，以连字符分割。改动比较多，新建一个分支，提交完再合并到主分支。

1

git switch --create customize-tag-titles

使用 VS Code 插件 Front Matter CMS 修改标签名。

加标签标题就比较繁琐，要自己创建文件。我让 ChatGPT 给我写了个脚本，好使！

我说的话：

I am customizing tag titles in a Hugo website. I want you to create a CLI program.
1
create-tag-title directory tag-name tag-title
If I run
1
create-tag-title content/en arch-linux 'Arch Linux'
the program should create content/en/tags/arch-linux/_index.md, the content of _index.md should be:
1
2
3
---
title: Arch Linux
---

ChatGPT 给的 Python 脚本（Shebang 是我加的¹）：

 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


#!/usr/bin/env python 
import os
import sys

def create_tag_title(directory, tag_name, tag_title):
 # Construct the path to the tag directory
 tag_dir = os.path.join(directory, 'tags', tag_name)
 
 # Make the directories if they don't exist
 os.makedirs(tag_dir, exist_ok=True)
 
 # Define the path for the _index.md file
 index_file_path = os.path.join(tag_dir, '_index.md')
 
 # Define the content of the _index.md file
 index_content = f"""---
title: {tag_title}
---
"""
 # Write the content to the _index.md file
 with open(index_file_path, 'w') as index_file:
 index_file.write(index_content)

 print(f"Created {index_file_path} with title: {tag_title}")

if __name__ == '__main__':
 # Ensure the correct number of arguments are provided
 if len(sys.argv) != 4:
 print("Usage: create-tag-title directory tag-name tag-title")
 sys.exit(1)

 # Read the arguments from the command line
 directory = sys.argv[1]
 tag_name = sys.argv[2]
 tag_title = sys.argv[3]

 # Call the function to create the tag title file
 create_tag_title(directory, tag_name, tag_title)

自己写提交信息还是太繁琐，让 ChatGPT 把这部分也加上。

我说的话：

Besides creating the _index.md, I want to stage content/ directory and commit. Example:
1
git add content/; git commit -m 'tag-title: arch-linux -> Arch Linux'

ChatGPT 返回的代码（Shellbang 是我加的）：

 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


#!/usr/bin/env python
import os
import sys
import subprocess

def create_tag_title(directory, tag_name, tag_title):
 # Construct the path to the tag directory
 tag_dir = os.path.join(directory, 'tags', tag_name)
 
 # Make the directories if they don't exist
 os.makedirs(tag_dir, exist_ok=True)
 
 # Define the path for the _index.md file
 index_file_path = os.path.join(tag_dir, '_index.md')
 
 # Define the content of the _index.md file
 index_content = f"""---
title: {tag_title}
---
"""
 # Write the content to the _index.md file
 with open(index_file_path, 'w') as index_file:
 index_file.write(index_content)

 print(f"Created {index_file_path} with title: {tag_title}")

 # Stage the content directory
 try:
 subprocess.run(['git', 'add', directory], check=True)
 print(f"Staged {directory}")

 # Commit the changes
 commit_message = f'tag-title: {tag_name} -> {tag_title}'
 subprocess.run(['git', 'commit', '-m', commit_message], check=True)
 print(f"Committed with message: '{commit_message}'")
 except subprocess.CalledProcessError as e:
 print(f"Error during git operation: {e}")

if __name__ == '__main__':
 # Ensure the correct number of arguments are provided
 if len(sys.argv) != 4:
 print("Usage: create-tag-title directory tag-name tag-title")
 sys.exit(1)

 # Read the arguments from the command line
 directory = sys.argv[1]
 tag_name = sys.argv[2]
 tag_title = sys.argv[3]

 # Call the function to create the tag title file
 create_tag_title(directory, tag_name, tag_title)

我使用的 Python 版本是 3.12.4。

检查链接变化 #

可以在修改前后构建网站，用于对比。如果链接有变化，需要重定向旧链接。改了一堆东西，我已经没心思检查了，忽略此步骤。

参考资料 #

写完文章我才想到可以让 ChatGPT 加 Shebang ↩︎

Hugo：补全文章的 ISO 8601 日期

Sat, 25 May 2024 00:00:00 +0800

背景 #

本网站使用 Hugo 构建，文章日期（date）是这样的：

1

date: '2020-10-02'

这里缺少了时间和时区。于是我给全部文章都设置了同一个时区（时间没填就是 00:00:00），但这个办法有隐患。如果我在另一个时区写文章，这时新的文章还是使用了旧时区。所以最好在每篇文章写上日期、时间和时区。

Hugo 日期的格式为 ISO 8601，示例：

1

date: 2020-10-02T00:00:00+08:00

补全日期的方法就是去掉引号¹、补上 T00:00:00+08:00。T00:00:00 是时间，+08:00是时区。

修改日期前先给全部文章加上 lastmod（上次修改时间），不然修改日期后 lastmod 全部变成今天了。

操作流程 #

在根目录新建 use-iso8601-date.sh，添加执行权限。

1
2


touch use-iso8601-date.sh
chmod +x use-iso8601-date.sh

在 use-iso8601-date.sh 填入脚本内容。

1
2
3
4
5
6
7
8


#!/usr/bin/env bash
# usage: ./use-iso8601-date.sh directory-name
directory="$1"
files=$(find "$directory" -type f)
for file in $files; do
 sed -i "s|date: '\(.*\)'|date: \1T00:00:00+08:00|g" "$file"
 sed -i 's|date: "\(.*\)"|date: \1T00:00:00+08:00|g' "$file"
done

修改前先构建网站，后面用于对比。

1
2
3


rm --recursive public/
hugo
mv public public-original

补全日期。

1

./use-iso8601-date.sh content

删除时区配置。

1
2
3
4


# config.toml

# 删掉下面这行
timeZone = "Etc/GMT-8"

再次构建网站。

1
2


hugo
mv public public-changed

使用文件对比工具（我用的是 Kompare）对比 public-original 和 public-changed，有一处差异：/en/post/2023/11/06/hugo-top-level-404/ 文内代码块的日期也被修改了。这样改也没错。

预览，稍微和 https://cyrusyip.org/ 对比一下，看起来一样。

1

hugo server

删除构建的网站。

1

rm --recursive public public-original public-changed

查看差异后提交改动。

1
2
3


git diff
git add --update
git commit --message 'feat: use ISO 8601 date'

删除脚本。

1

rm use-iso8601-date.sh

日期的引号去不去都行，我觉得不用更简洁就选择去掉。 ↩︎

Hugo：给文章添加 lastmod（上次修改时间）

Sat, 25 May 2024 00:00:00 +0800

背景：本站文章的 lastmod（上次修改时间）就是 Git 提交的 author date（作者日期）。我需要批量修改文章（Hugo：补全文章的 ISO 8601 日期），这会导致所有文章的 lastmod 都变成今天。文章内容没变就不应该改 lastmod，所以我打算给每篇文章都加上 lastmod，后面改动文章就 lastmod 就不会变。

先把 lastmod 的优先级调至最高，不然 Hugo 会继续使用 Git 提交日期。

1
2
3


# config.toml
[frontmatter]
 lastmod = ['lastmod', ':default']

在根目录新建 add-lastmod.sh，添加执行权限

1
2


touch add-lastmod.sh
chmod +x add-lastmod.sh

往 add-lastmod.sh 填入脚本内容。

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


#!/usr/bin/env bash
# usage: ./add-lastmod.sh directory-name
directory="$1"
files=$(find "$directory" -type f)
for file in $files; do
 echo "${file}"
 lastmod_date=$(git log --no-show-signature -1 --format=%aI "$file") # example: 2024-05-16T14:23:53+08:00
 echo "$lastmod_date"
 # Use awk to insert the lastmod line above the second ---
 awk -v lastmod="lastmod: $lastmod_date # remove this line if the content is actually changed" '
 BEGIN { frontmatter = 0 }
 /^---$/ { frontmatter++ }
 frontmatter == 2 && !printed { print lastmod; printed = 1 }
 { print }
 ' "$file" >tmpfile && mv tmpfile "$file"
done

修改前先构建网站，后面用于对比。

1
2
3


rm --recursive public/
hugo
mv public public-original

添加 lastmod。

1

./add-lastmod.sh content

再次构建网站。

1
2


hugo
mv public public-changed

使用文件对比工具（我用的是 Kompare）对比 public-original 和 public-changed，结果完全相同。

预览，稍微和 https://cyrusyip.org/ 对比一下，看起来一样。

1

hugo server

删除构建的网站。

1

rm --recursive public public-original public-changed

查看差异后提交改动。

1
2
3


git diff
git add --update
git commit --message 'chore: add lastmod before changing date'

删除脚本。

1

rm add-lastmod.sh

把 Hugo 网站从 Vercel 搬到 Cloudflare Pages

Sun, 05 Nov 2023 00:00:00 +0800

起因 #

本 Hugo 网站原本使用 Vercel 构建，但是它只获取 Git 源代码仓库的前十次提交¹，多数文章的更新时间会出错，变成最新提交的时间。于是我就改用支持克隆整个仓库的 Cloudflare Pages。本站的 RSS 订阅文件消耗流量大，搬到无限流量的 Cloudflare Pages 也比较合适。本文发布时本站已搬到 Cloudflare Pages 超过一个月，一切正常。

搬迁的主要步骤包括：写重定向配置文件、解决 Cloudflare Pages 导致的问题、创建 Cloudflare Pages 应用、删除 Vercel 项目。

重定向配置 #

Cloudflare Pages 的重定向配置写法和 Vercel 不一样。参考 Redirects · Cloudflare Pages docs 写一份。

Vercel 的重定向配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
 "redirects": [
 {
 "source": "/(index.xml)",
 "destination": "/zh-cn/$1"
 },
 {
 "source": "/(post/index.xml)",
 "destination": "/zh-cn/$1"
 },
 {
 "source": "/(about|subscribe|donate)(/?)",
 "destination": "/zh-cn/$1$2"
 },
 {
 "source": "(/post/[0-9].*)",
 "destination": "/zh-cn$1"
 },
 {
 "source": "/(tags|categories)(/?.*)",
 "destination": "/zh-cn/$1$2"
 }
 ]
}

Cloudflare Pages 的重定向配置：

 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


# This file is used by Cloudflare Pages
# To improve performance, put splats and placeholders to the bottom

###########################
### Old Chinese Website ###
###########################
## RSS
/index.xml /zh-cn/index.xml 308
/index.xml/ /zh-cn/index.xml 308
/post/index.xml /zh-cn/post/index.xml 308
/post/index.xml/ /zh-cn/post/index.xml 308
## Menu
/about /zh-cn/about/ 308
/about/ /zh-cn/about/ 308
/subscribe /zh-cn/subscribe/ 308
/subscribe/ /zh-cn/subscribe/ 308
/donate /zh-cn/donate/ 308
/donate/ /zh-cn/donate/ 308
/tags /zh-cn/tags/ 308
/categories /zh-cn/categories/ 308
/tags/* /zh-cn/tags/:splat 308
/categories/* /zh-cn/categories/:splat 308
## Post
/post/:year/:month/:day/:slug /zh-cn/post/:year/:month/:day/:slug/ 308
/post/:year/:month/:day/:slug/ /zh-cn/post/:year/:month/:day/:slug/ 308
# Examples:
# /post/2020/10/02/ubuntu-compile-goldendict
# /post/2020/10/02/ubuntu-compile-goldendict/


#######################
### Current Website ###
#######################
## RSS links shouldn't contain a trailing slash
/en/index.xml/ /en/index.xml 308
/zh-cn/index.xml/ /zh-cn/index.xml 308

在根目录创建 404 页面 #

本 Hugo 多语言网站的 defaultContentLanguageInSubdir = "true" 配置导致构建网站后根目录没有 404.html 文件，/en/ 和 /zh-cn/ 才有。此时 Cloudflare 认为网站是单页应用，用户访问 /non-existent-page/ 这样的路径网页就会跳转到 / 并且返回 200 状态码。这是错误的行为，所以要让 Hugo 构建后根目录有 404.html。解决方法请看 Create Top-Level 404 Page for a Multilingual Hugo Site，我目前使用了自己写的 404 页面。

去掉缓存规则 #

之前在 Cloudflare 设置了缓存 RSS 文件，现在不需要这些规则了，删除之。

自定义样式使用 SCSS 格式 #

Cloudflare 会缓存 custom.css，改用 SCSS 格式就不会出问题。

创建应用 #

使用以下配置创建 Cloudflare Pages 应用，然后配置域名。

Build settings
`Framework preset`	`None`
`Build command`	`git fetch --unshallow && hugo`
`Build output directory`	`public`

Environment variables
`HUGO_VERSION`	`0.99.1`

具体操作请看教程：

Cloudflare Pages 的缺点 #

重定向不支持正则表达式
一个仓库只能导入一次
不支持配置文件

重定向例子 #

Configuring a Build | Vercel Docs: When you make a deployment, Vercel builds your project. During this time, Vercel performs a “shallow clone” on your Git repository using the command git clone --depth=10 (...) and fetches ten levels of git commit history. This means that only the latest ten commits are pulled and not the entire repository history. ↩︎

Hugo 多语言博客折腾记

Mon, 30 May 2022 00:00:00 +0800

最近在统计之都看大家讨论博客，又激起了我的折腾之心，打算把一个大坑给填了：把中文博客改为双语博客。我先建立了一个新的 Git 分支来折腾，成功后才合并到主分支。以下是详细的折腾过程。

改用 jane 主题 #

我原来用的 even 主题年久失修，作者超过一年没出来处理 Issue 和 Pull Request 了，这个主题的多语言配置也没有详细的说明和配置，于是我就改用 jane 主题，这个主题更新及时，要是出 bug 应该也容易解决。jane 主题有现成的多语言配置可以抄，而且手机页面也有目录。

这次改用 git submodule 添加主题，这样就不用把主题里的一堆文件加进 git 仓库了。

1

git submodule add https://github.com/xianmin/hugo-theme-jane.git themes/jane

配置就抄这几个文件：

1
2
3


./exampleSite/config.toml
./exampleSite/full-config.toml
./dev-config.toml

双语配置是这样的：

 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


defaultContentLanguageInSubdir = "true" # Render English site under /en
[permalinks]
 post = "/post/:year/:month/:day/:slug/"
# language support # en / zh-cn / other... translations present in i18n/
defaultContentLanguage = "en" # Default language to use
[langusges]
[languages.en]
 title = "Cyrus Yip's Blog"
 languageName = "English"
 contentDir = 'content/en'
 # languageCode = "en"
 # weight = 2
[languages.zh-cn]
 title = "叶寻的博客"
 languageName = "简体中文"
 contentDir = 'content/zh-cn'
 # languageCode = "zh-cn"
 # weight = 1
[author] # essential # 必需
 name = "Cyrus Yip 叶寻"

[[languages.en.menu.main]]
 name = "Home"
 weight = 10
 identifier = "home"
 url = "/"

[[languages.en.menu.main]]
 name = "Archives"
 weight = 20
 identifier = "archives"
 url = "/post/"
[[languages.en.menu.main]]
 name = "Tags"
 weight = 30
 identifier = "tags"
 url = "/tags/"
[[languages.en.menu.main]]
 name = "Categories"
 weight = 40
 identifier = "categories"
 url = "/categories/"

[[languages.zh-cn.menu.main]]
 name = "主页"
 weight = 10
 identifier = "home"
 url = "zh-cn/"
[[languages.zh-cn.menu.main]]
 name = "归档"
 weight = 20
 identifier = "archives"
 url = "zh-cn/post/"
[[languages.zh-cn.menu.main]]
 name = "标签"
 weight = 30
 identifier = "tags"
 url = "zh-cn/tags/"
[[languages.zh-cn.menu.main]]
 name = "分类"
 weight = 40
 identifier = "categories"
 url = "zh-cn/categories/"

内容目录改成这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


❯ tree content
content
├── en
│   ├── abount.md
│   └── post
│   └── 2022-05-24-hello-world.md
└── zh-cn
 ├── about.md
 └── post
    └── 2020-10-02-ubuntu-compile-goldendict.md

URL 重定向 #

网站改为双语之后，网站链接和原来的不一样了，需要把旧链接重定向到新链接。中文博客链接现在多了 zh-cn，以前是这样的：https://cyrusyip.org/post/2020/10/02/ubuntu-compile-goldendict/，现在要改成 https://cyrusyip.org/zh-cn/post/2020/10/02/ubuntu-compile-goldendict/。RSS 链接也要改。我用 Vercel 部署网站，所以修改 vercel.json，使用正则表达式来重定向链接。改动链接和迁移评论前最好关闭网站，以免造成同一篇文章出现两份评论。

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


 "redirects": [
 {
 "source": "/post/(index.xml)",
 "destination": "/zh-cn/$1"
 },
 {
 "source": "/(about|subscribe|donate)(/?)",
 "destination": "/zh-cn/$1$2"
 },
 {
 "source": "(/post/[0-9].*)",
 "destination": "/zh-cn$1"
 }
 ]

Vercel 重定向的官方文档也没介绍它支持哪种正则表达式，我就参照益辉的配置自己尝试了。如果你像我一样对正则表达式读写困难，可以用 regex visualizer 帮助理解。修改后的完整 vercel.json 在这里。弄好之后可以用 Google Search Console 再看看有没有错误链接。

改动内部链接 #

网站源文件里面的链接也要更改，例如：[本站的某文章](/post/2021/01/01/hi/) 要改为 [本站的某文章](/zh-cn/post/2021/01/01/hi/)、https://cyrusyip.org/post/xxx 改为 https://cyrusyip.org/zh-cn/post/xxx。

用 ripgrep 查找源文件里需要改的链接。

1
2


rg '\[.*\]\(/.*\)' content --only-matching >> todo/internal-links
rg 'cyrusyip\.org' content >> todo/internal-links

修正链接。

1

sed --regexp-extended -i "s|(\[.*\]\()(/.*\))|\1/zh-cn\2|g" content/zh-cn/post/*

剩下的漏网之鱼就自己手动改了。

更新博客列表的 RSS 链接 #

我的博客收录于下面这两个博客列表。

于是过去提交了 pull request 改 RSS 链接。其实不改也没事，旧链接会重定向到新链接。

迁移评论 #

本站的评论是和文章链接绑定的，因为文章链接改变了，所以要将评论指向新的链接，不然就看不到已有的评论了。本站的评论系统是 Disqus 和 utterances。

Disqus #

Disqus 评论使用 URL Mapper 修改。URL Mapper 使用 .csv 文件迁移评论，我先从 Disqus 那里拿到一个 .csv 文件。节选内容如下。

1
2
3
4


https://cyrusyip.org/about/
https://cyrusyip.org/donate/
https://cyrusyip.org/subscribe/
https://cyrusyip.org/post/2020/11/15/mute-volume-plasma/

将它加上逗号和新链接。

1
2
3
4


https://cyrusyip.org/about/,https://cyrusyip.org/zh-cn/about/
https://cyrusyip.org/donate/,https://cyrusyip.org/zh-cn/donate/
https://cyrusyip.org/subscribe/,https://cyrusyip.org/zh-cn/subscribe/
https://cyrusyip.org/post/2020/11/15/mute-volume-plasma/,https://cyrusyip.org/zh-cn/post/2020/11/15/mute-volume-plasma/

然后再上传到 Disqus 就可以迁移评论了，Disqus 会合并逗号两边的文章评论，并将评论移动到右边的链接。官方文档说可能需要 24 小时才完成迁移，实际上我迁移了 82 份评论，一瞬间就好了。修改 .csv 的每一行都是一样的操作：复制整行内容、加逗号、粘贴、加上 zh-cn，所以用 Vim 的 q 命令录制一次操作，然后就可以批量更改了。以下是操作视频，速度比较慢，可以调到 2 倍速观看。

视频 32 秒执行录制命令时特别慢，主要原因是 coc.nvim 和 fcitx.vim。用 Vim 默认配置（vim --clean）瞬间就完成了，看来录制命令最好在无插件下使用。我专门定义了命令来用 Vim 默认配置打开文件。

1
2


" Cv: clean vim, used for fast macro replaying
command Cv silent! w | wviminfo | !vim -c 'set rnu nuw=1' -c 'file' --clean -i ~/.viminfo %

Disqus 还有其他迁移方式，不过我觉得还是 URL Mapper 最稳妥。

utterances #

utterances 使用 GitHub Issue 保存评论。标题为「post/2021/10/11/build-aur-wps/」的 Issue 对应的文章链接为「https://cyrusyip.org/post/2021/10/11/build-aur-wps/」。使用 GitHub CLI 修改 Issue 标题就可以迁移评论。

保存 Issue 标题与号码，并用 Vim 打开。

1
2
3


mkdir todo
gh issue --repo CyrusYip/blog-comment list > todo/utterances
vim todo/utterances

Issue 信息是这样的：

1
2
3


3	OPEN	about/		2021-10-05 07:07:15 +0000 UTC
2	OPEN	post/2021/03/15/liangfen-shaoxiancao-guilinggao/		2021-04-30 06:53:25 +0000 UTC
1	OPEN	post/2021/03/08/girls-day-womens-day-and-goddesses-day/		2021-03-17 14:46:31 +0000 UTC

这里用 Vim 的 q 命令批量处理上面的内容，使其变成：

1
2
3


gh issue --repo CyrusYip/blog-comment edit 3 --title 'zh-cn/about/'
gh issue --repo CyrusYip/blog-comment edit 2 --title 'zh-cn/post/2021/03/15/liangfen-shaoxiancao-guilinggao/'
gh issue --repo CyrusYip/blog-comment edit 1 --title 'zh-cn/post/2021/03/08/girls-day-womens-day-and-goddesses-day/'

然后在 Vim 执行 :%!bash，用 BASH 执行上面的命令。utterances 只能移动评论，不能合并评论。移动前最好关闭网站，以免造成同一篇文章出现两份评论。

增加标题级别 #

之前我写文章都是先用 Markdown 的一级标题，但根据 MDN 和 Bing Webmaster Tools，使用多个 <h1> 标题是错误的。

Use only one <h1> per page or view. It should concisely describe the overall purpose of the content.

Using more than one <h1> is allowed by the HTML specification, but is not considered a best practice. Using only one <h1> is beneficial for screenreader users.

—https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#usage_notes

These pages have more than one <h1> tag. Multiple <h1> header tags might confuse search engine bots and website’s users. It is recommended to use only one <h1> tag per page.

—SEO Reports from Bing Webmaster Tools

这次难得折腾，就彻底整改吧。依然是用正则表达式解决：

1

find content/ -type f -exec perl -0777 -i -pe 's/(?<=\n\n)(#.*)(?=\n\n)/#$1/g' {} +

上面的正则表达式查找的是「以 # 开头的行，并且它上下都有 1 个空行」，然后在查找到的内容前面增加 #，也就是增加了 1 个标题级别。处理完之后用 VS Code 手动检查，没问题就提交 commit。可以用 VS Code 搜索 ^# ，看看有没有遗漏的。

preservim/vim-markdown 的 :HeaderIncrease 和 pandoc 的 --shift-heading-level-by=1 选项也可以用来增加标题级别。但是这两个工具都有问题，vim-markdown 会将 Markdown 文件 YAML 内容后两行当成标题，pandoc 会修改 YAML 内容。还是自己老老实实写的正则表达式好。

添加 favicon #

用 https://realfavicongenerator.net/ 将我的头像做成 favicon，放到 /static 文件夹。

Jane 主题的问题 #

从 Even 主题切换到 Jane，还是遇到了一些小问题。

没有文章总数功能，Even 主题是有的（解决办法：在博客目录用 tree content/ 命令查看文件数）。
不蒜子流量统计在英文博客下仍显示中文。
不能给不同语言设置不同作者名，例如：中文博客作者是「叶寻」，英文博客作者是「Cyrus Yip」（临时解决办法：中英名字都写入作者名，也就是「Cyrus Yip 叶寻」）。
用 Vercel 部署博客时 params.gitInfo 功能会出错，本地部署就没事，不知道咋回事。

修改网站是永无止境的，这些小问题就忍忍吧，太纠结反而没时间写文章了。博客内容最重要，功能够用外观不丑就行。

代办事项 #

这是我想做的一些事。先挖坑，~~看看有没有人帮我埋~~。

自动备份 utterances 评论
自动备份 Disqus 评论

资料和工具 #

E Personal Experience | blogdown: Creating Websites with R Markdown（谢益辉的博客写作经验）
iggredible/Learn-Vim: Learn Vim (the Smart Way)（Vim 教程，学完第九章 Macros 就能在迁移评论时批量处理）
ziishaned: Learn regex the easy way（正则表达式入门教程）
regex visualizer（正则表达式可视化工具，用于理解正则表达式，上谷歌能搜到很多）
vimtutor（Vim 的官方教程，先学这个，再学 Learn-Vim）

让 Hugo 自动给图片加上说明文字

Thu, 11 Mar 2021 00:00:00 +0800

本文测试于 Hugo extended 0.125.6，完整的网站代码在此。

将图片标题用作说明文字（推荐） #

Markdown 插入图片的代码是这样的：

1

![描述](链接 "标题")

对于的 HTML 代码：

1

<img src="链接" alt="描述" title="标题" />

用户的光标放在图片时，会有提示框，其内容为标题。提示框不好用，因为用户不一定会把光标移动到图片上，而且用户可能不用鼠标。

既然提示框不好用，那我们可以将标题转换为图片底下的说明文字，这样用户一定会看到。对应的 HTML 代码为：

1
2
3
4


<figure>
 <img src="链接" alt="描述">
 <figcaption>标题</figcaption>
</figure>

配置流程：

在博客根目录下新建 layouts/_default/_markup/render-image.html

1
2


mkdir layouts/_default/_markup/ -p
touch layouts/_default/_markup/render-image.html

往 render-image.html 填入以下内容（如果不需要修改样式，可以去除 class="..."）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{{ if .Title }}
 <figure class="figure">
 <img class="img" src="{{ .Destination | safeURL }}"
 {{- with .Text }} alt="{{ . }}"{{ end -}} >
 <figcaption>{{ .Title }}</figcaption>
 </figure>
{{ else }}
 <img class="img" src="{{ .Destination | safeURL }}"
 {{- with .Text }} alt="{{ . }}"{{ end -}} >
{{ end }}

![](https://upload.wikimedia.org/wikipedia/commons/1/1f/Wiki-sisters.png "维基娘的姊妹们（由左至右）：维基共享资源娘、维基百科娘、维基语录娘") 会显示成这样。

如果不需要说明文字，就写 ![维基娘的姊妹们（由左至右）：维基共享资源娘、维基百科娘、维基语录娘](https://upload.wikimedia.org/wikipedia/commons/1/1f/Wiki-sisters.png)。

将图片描述用作说明文字（不推荐） #

不推荐此方法的原因是 <img> 元素的 alt 属性（描述）和 <figcaption> 元素意义不同，将前者转换成后者是错的。

如果你的 Markdown 图片链接是只有描述没有标题，也可以把描述变成说明文字。render-image.html 需要改为：

1
2
3
4


<figure class="figure">
 <img class="img" src="{{ .Destination | safeURL }}" alt="{{ .Text }}">
 <figcaption>{{ .Text }}</figcaption>
</figure>

![维基娘的姊妹们（由左至右）：维基共享资源娘、维基百科娘、维基语录娘](https://upload.wikimedia.org/wikipedia/commons/1/1f/Wiki-sisters.png) 会显示成这样。

样式 #

我给本站加了一些额外的样式，你可以根据你的需求调整你的网站。!important 必要时才用。

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


/* remove figure margin */
figure {
 margin: 0 !important;
}
figure > figcaption {
 color: gray;
}
/* image is not clickable because photoswipe is disabled */
p > img {
 cursor: auto !important;
}
/* center img */
// :has only works for browsers after December 2023, see https://caniuse.com/css-has
p:has(.img), .figure{
 text-align: center;
}

用表格添加说明文字 #

我还在 Stack Overflow 发现了一个怪招：使用单列双行的表格，第一行放图片，第二行放说明文字。

1
2
3


|![](图片链接)|
|:-:|
|说明文字|

1
2
3


| ![](https://www.storywarren.com/wp-content/uploads/2016/09/space-1.jpg) |
|:--:|
| Space |

Hugo on 叶寻的博客

优化 Hugo 博客速度：Pjax、dynamic script、preload、minification

Pjax 免刷新加载页面 #

Dynamic Script 动态插入脚本 #

rel=preload 预加载 #

Minification 极简化 #

相关代码 #

感想 #

参考资料 #

2024-08-03 本站改动：使用 Yue 主题和 giscus 评论，post 目录改为 posts

清理无用文件 #

将主题换为 Yue #

添加本站原有的功能 #

将 utterances 评论改为 giscus #

post 文件夹改为 posts #

重命名文件夹 #

修改文章内部链接 #

重定向 #

关闭评论 #

迁移 Disqus 评论 #

迁移 giscus 评论 #

查看评论 #

开启评论 #

Hugo：自定义标签标题

背景 #

修改标签单页标题（/zh-cn/tags/*/） #

修改文章底下的标签标题（/zh-cn/post/*） #

修改标签列表页面（/zh-cn/tags/） #

修改所有标签名，加上标签标题 #

检查链接变化 #

参考资料 #

Hugo：补全文章的 ISO 8601 日期

背景 #

操作流程 #

Hugo：给文章添加 lastmod（上次修改时间）

把 Hugo 网站从 Vercel 搬到 Cloudflare Pages

起因 #

重定向配置 #

在根目录创建 404 页面 #

去掉缓存规则 #

自定义样式使用 SCSS 格式 #

创建应用 #

Cloudflare Pages 的缺点 #

重定向例子 #

Hugo 多语言博客折腾记

改用 jane 主题 #

URL 重定向 #

改动内部链接 #

更新博客列表的 RSS 链接 #

迁移评论 #

Disqus #

utterances #

增加标题级别 #

添加 favicon #

Jane 主题的问题 #

代办事项 #

资料和工具 #

让 Hugo 自动给图片加上说明文字

将图片标题用作说明文字（推荐） #

将图片描述用作说明文字（不推荐） #

样式 #

用表格添加说明文字 #

参考资料 #

修改标签单页标题（`/zh-cn/tags/*/`） #

修改文章底下的标签标题（`/zh-cn/post/*`） #

修改标签列表页面（`/zh-cn/tags/`） #