Hugo 博客搭建經驗總結

我用的主題是 PaperMod，本文用它來作示例。

所有路徑必須使用相對路徑（不要加前導斜杠）！

目錄#

如果要在文章頁面中顯示目錄，請關注以下配置：

params:
  showToc: true # 全局顯示目錄
  tocopen: true # 全局目錄展開（目錄默認是折疊列表）

多語言#

這裡的配置很容易出問題。如果你像我一樣喜歡搞多語言博客，請關注以下配置：

defaultContentLanguage: zh-cn
defaultContentLanguageInSubdir: true

defaultContentLanguage: zh-cn

設置網站默認語言為簡體中文
影響 Hugo 生成的 URL 結構
決定默認內容的語言標識

以上配置不要修改，除非的確要修改默認語言。

defaultContentLanguageInSubdir: true

控制默認語言內容是否放在子目錄中
true: 默認生成路徑為 zh-cn/posts/
false: 默認生成路徑為 posts/

舉例：

# 當 defaultContentLanguageInSubdir: true
public/
├── zh-cn/          # 默認語言(中文)內容
│   └── posts/
└── en/             # 其他語言內容
    └── posts/

# 當 defaultContentLanguageInSubdir: false
public/
├── posts/          # 默認語言(中文)內容
└── en/             # 其他語言內容
    └── posts/

需要配置多語言 content 目錄：

languages:
  zh-cn:
    languageName: "簡體中文"
    contentDir: "content/zh-cn" # content/<lang>
    # ... 需要做多語言配置的配置都可以寫進這裡
  en:
    languageName: "English"
    contentDir: "content/en"
    # ...

在多語言配置下，search.md 和 archive.md 有效路徑為：

content/
├── zh-cn/
│   ├── posts/
│   ├── search.zh-cn.md # search.<lang>.md
│   └── archive.md
└── en/
    ├── posts/
    ├── search.en.md
    └── archive.md

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

languages:
  zh-cn:
    menu:
      main:
        - identifier: "search"
          name: "搜索"
          url: "search"
          weight: 1
        - identifier: "archives"
          name: "歸檔"
          url: "archives"
          weight: 2

搜索#

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

outputs:
  home:
    - HTML
    - RSS
    - JSON # JSON 是支持搜索的關鍵

字體#

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

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

@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 變量決定了代碼塊背景色：

.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 中有兩處聲明了這個變量：

: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” 標題下會出現形如以下內容：

<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 中啟用了評論：

params:
  comments: true

推送#

敲打 hugo -D 命令後，Hugo 會在 public 目錄下構建靜態博客。每次構建前一般會將 public 刪掉來確保新構建的內容不出問題。

在這種情況下，我希望只部署靜態博客到倉庫中，而不是整個 Hugo 框架。於是寫了一個 Shell 腳本：

@echo off
hugo -D
cd public
git init
git remote add origin git@github.com:<user>/<repo>.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 ..

因為不方便維護，我又改用同一倉庫中單獨創建源碼分支和部署分支的方法。於是乎：

# 在主倉庫創建 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。