Hugo 博客搭建经验总结

我用的主题是 PaperMod，本文用它来作示例。

多语言

这里的配置很容易出问题。如果你像我一样喜欢搞多语言博客，请关注以下配置：

1
2
defaultContentLanguage: zh-cn
defaultContentLanguageInSubdir: true

defaultContentLanguage: zh-cn

设置网站默认语言为简体中文
影响 Hugo 生成的 URL 结构
决定默认内容的语言标识

以上配置不要修改，除非的确要修改默认语言。

defaultContentLanguageInSubdir: true

控制默认语言内容是否放在子目录中
true: 默认生成路径为 /zh-cn/posts/
false: 默认生成路径为 /posts/

举例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 当 defaultContentLanguageInSubdir: true
public/
├── zh-cn/          # 默认语言(中文)内容
│   └── posts/
└── en/             # 其他语言内容
    └── posts/

# 当 defaultContentLanguageInSubdir: false
public/
├── posts/          # 默认语言(中文)内容
└── en/             # 其他语言内容
    └── posts/

需要配置多语言 content 目录：

1
2
3
4
5
6
7
8
9
languages:
  zh-cn:
    languageName: "简体中文"
    contentDir: "/content/zh-cn" # /content/<lang>
    # ... 需要做多语言配置的配置都可以写进这里
  en:
    languageName: "English"
    contentDir: "/content/en"
    # ...

在多语言配置下，search.md 和 archive.md 有效路径为：

1
2
3
4
5
6
7
8
9
content/
├── zh-cn/
│   ├── posts/
│   ├── search.zh-cn.md # search.<lang>.md
│   └── archive.md
└── en/
    ├── posts/
    ├── search.en.md
    └── archive.md

以上两者的 URL 在 hugo.yaml 中保持一般设置即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
languages:
  zh-cn:
    menu:
      main:
        - identifier: "search"
          name: "搜索"
          url: "/search"
          weight: 1
        - identifier: "archives"
          name: "归档"
          url: "/archives"
          weight: 2

搜索

要支持搜索功能，必须在 hugo.yaml 中做如下配置：

1
2
3
4
5
outputs:
  home:
    - HTML
    - RSS
    - JSON # JSON 是支持搜索的关键

字体

我想要英文使用 Ubuntu Mono，中文使用 HarmonyOS Sans SC，代码使用 JetBrains Mono，于是做了如下配置。

新建 /themes/PaperMod/assets/css/extended/fonts.css：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
@import url('https://cdn.jsdelivr.net/npm/ubuntu-mono/css/ubuntu-mono.min.css?display=swap');
@import url('https://cdn.jsdelivr.net/npm/harmonyos-sans-font/css/harmonyos-sans.min.css?display=swap');
@import url('https://cdn.jsdelivr.net/npm/jetbrains-mono/css/jetbrains-mono.min.css?display=swap');

body {
  font-family: "Ubuntu Mono", "HarmonyOS Sans SC", sans-serif;
}

code, pre {
  font-family: "JetBrains Mono", monospace;
}

代码块背景色

默认的代码块背景色亮度很低（非常黑），我修改了一下。

在 /themes/PaperMod/assets/css/common/post-single.css 第 206 行处，可以看到 --code-block-bg 变量决定了代码块背景色：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.post-content pre code {
    display: grid;
    margin: auto 0;
    padding: 10px;
    color: rgb(213, 213, 214);
    background: var(--code-block-bg) !important;
    border-radius: var(--radius);
    overflow-x: auto;
    word-break: break-all;
}

全局搜索后发现 /themes/PaperMod/assets/css/core/theme-vars.css 中有两处声明了这个变量：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
:root {
    ...
    --code-block-bg: rgb(43, 43, 43);
    ...
}

.dark {
    ...
    --code-block-bg: rgb(43, 43, 43);
    ...
}

都改成 rgb(43, 43, 43) 就可以了。

我使用的是 Giscus，它是利用 GitHub Discussions 实现的评论系统。

请确保：

博客仓库是公开的，否则访客将无法查看 Discussions。
giscus app 已安装，否则访客将无法评论和回应。
Discussions 功能已在仓库中启用。

然后访问 Giscus 网站，按要求进行配置。

配置完成后，在“启用 giscus”标题下会出现形如以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<script src="https://giscus.app/client.js"
        data-repo="[在此输入仓库]"
        data-repo-id="[在此输入仓库 ID]"
        data-category="[在此输入分类名]"
        data-category-id="[在此输入分类 ID]"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

新建 /layouts/partials/comments.html，将得到的 <script> 标签复制粘贴进去。

确保 hugo.yaml 中启用了评论：

1
2
params:
  comments: true

推送

敲打 hugo -D 命令后，Hugo 会在 /public 目录下构建静态博客。每次构建前一般会将 /public 删掉来确保新构建的内容不出问题。

在这种情况下，我希望只部署静态博客到仓库中，而不是整个 Hugo 框架。于是写了一个 Shell 脚本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@echo off
hugo -D
cd public
git init
git remote add origin git@github.com:zzzhizhiw/zzzhizhi-blog.git
git checkout -b main
git fetch
git add -A
git commit -m "temp"
git reset --soft origin/main
git commit -m "update %date%"
git push
cd ..

因为不方便维护，我又改用同一仓库中单独创建源码分支和部署分支的方法。于是乎：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# 在主仓库创建 public 分支
git checkout --orphan public
git reset --hard
git commit --allow-empty -m "Init public branch"
git push origin public
git checkout main

# 将 public 目录关联到 public 分支
git worktree add -B public public origin/public

# 生成网站并推送
hugo -D
cd public
git add -A
git commit -m "Push %date%"
git push origin public
cd ..

结合 Cloudflare Pages 自带 CI/CD，只需一个脚本即可实现一键推送更新。

不要在 hugo.yaml 中配置 baseURL，这会导致所有部署唯一预览 URL 被重定向到 baseURL。

`hugo.yaml` 示例

这是我使用的 hugo.yaml。

目录#

多语言#

搜索#

字体#

代码块背景色#

评论#

推送#

hugo.yaml 示例#

目录

多语言

搜索

字体

代码块背景色

评论

推送

`hugo.yaml` 示例