Hugo Blog Setup Experiences Summary

I am using the PaperMod theme, and this article uses it as an example.

If you want to display a table of contents on the article page, note the following configuration:

1
2
3
params:
  showToc: true # Show table of contents globally
  tocopen: true # Expand the table of contents globally (the table is collapsed by default)

Multilingual

It’s easy to make mistakes here. If you, like me, want a multilingual blog, pay attention to:

1
2
defaultContentLanguage: zh-cn
defaultContentLanguageInSubdir: true

defaultContentLanguage: zh-cn

Sets the default language to Simplified Chinese
Affects the URL structure generated by Hugo
Determines the language identifier for default content

The above configuration should not be modified unless you specifically need to change the default language.

defaultContentLanguageInSubdir: true

Controls whether default language content is placed in a subdirectory
true: default path is /zh-cn/posts/
false: default path is /posts/

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# When defaultContentLanguageInSubdir: true
public/
├── zh-cn/
│   └── posts/
└── en/
    └── posts/

# When defaultContentLanguageInSubdir: false
public/
├── posts/
└── en/
    └── posts/

You need to configure the multilingual content directory:

1
2
3
4
5
6
7
8
9
languages:
  zh-cn:
    languageName: "简体中文"
    contentDir: "/content/zh-cn" # /content/<lang>
    # ... other multilingual configurations ...
  en:
    languageName: "English"
    contentDir: "/content/en"
    # ...

Under multilingual configuration, the valid paths for search.md and archive.md are:

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

The URLs of both in hugo.yaml can remain generally configured:

 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

Search

To support search functionality, the following configuration must be done in hugo.yaml:

1
2
3
4
5
outputs:
  home:
    - HTML
    - RSS
    - JSON # JSON is the key to enabling search

Fonts

I wanted to use Ubuntu Mono for English, HarmonyOS Sans SC for Chinese, and JetBrains Mono for code, so I added the following configuration.

Create /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;
}

Code Block Background Color

By default, the brightness of the code block background is very low (quite dark). I modified it slightly.

In /themes/PaperMod/assets/css/common/post-single.css around line 206, you can see the variable --code-block-bg controlling the code block background color:

 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;
}

Search globally and find /themes/PaperMod/assets/css/core/theme-vars.css, where this variable is declared in two places:

 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);
    ...
}

Set both to rgb(43, 43, 43).

Comments

I use Giscus, which leverages GitHub Discussions as a commenting system.

Make sure:

The blog repository is public, or visitors can’t view the Discussions.
The giscus app is installed, or visitors can’t comment or respond.
Discussions is enabled in the repository.

Then, go to the Giscus site and configure as required.

After configuration, under “Enable giscus,” content like the following will appear:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<script src="https://giscus.app/client.js"
        data-repo="[enter repository here]"
        data-repo-id="[enter repository ID here]"
        data-category="[enter category name here]"
        data-category-id="[enter category ID here]"
        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>

Create /layouts/partials/comments.html and copy the <script> tag.

Ensure hugo.yaml has comments enabled:

1
2
params:
  comments: true

Deployment

After running hugo -D, Hugo builds the static blog into /public. Typically, delete /public before each build to avoid issues.

I only want to deploy the static blog, not the entire Hugo framework, so I wrote a Shell script:

 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 ..

Due to maintenance difficulties, I switched to using separate source and deployment branches within the same repository. Therefore:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Create public branch in main repository
git checkout --orphan public
git reset --hard
git commit --allow-empty -m "Init public branch"
git push origin public
git checkout main

# Link public directory to public branch
git worktree add -B public public origin/public

# Generate site and push
hugo -D
cd public
git add -A
git commit -m "Push %date%"
git push origin public
cd ..

With Cloudflare Pages CI/CD, a single script can push updates with one command.

Do not configure baseURL in hugo.yaml; otherwise, all unique preview URLs will be redirected to baseURL.

`hugo.yaml` Example

Below is the hugo.yaml I use:

  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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
languageCode: zh-cn
theme: PaperMod

pagination:
  paperSize: 5

enableRobotsTXT: true
buildDrafts: false
buildFuture: true
buildExpired: true
enableEmoji: true
enableGitInfo: true

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production
  keywords: [致之, zzzhizhi, Blog]
  images: ["<link or path of image for opengraph, twitter-cards>"]
  DateFormat: "2006-01-02"
  defaultTheme: auto
  disableThemeToggle: false

  ShowReadingTime: true
  ShowShareButtons: false
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  UseHugoToc: true
  disableSpecial1stPost: false
  disableScrollToTop: false
  comments: true
  hidemeta: false
  hideSummary: false
  showToc: true
  tocopen: true

  assets:
    disableHLJS: true
    disableFingerprinting: true

    favicon: "/favicon.ico"
    favicon16x16: "/favicon-16x16.ico"
    favicon32x32: "/favicon-32x32.ico"
    apple_touch_icon: "/apple-touch-icon.jpg"
    safari_pinned_tab: "/safari-pinned-tab.svg"

  homeInfoParams:
    Title: "Hi there \U0001F44B"
    Content: Welcome to my blog

  analytics:
    google:
      SiteVerificationTag: "XYZabc"
    bing:
      SiteVerificationTag: "XYZabc"
    yandex:
      SiteVerificationTag: "XYZabc"

  cover:
    hidden: true
    hiddenInList: true
    hiddenInSingle: true

  fuseOpts:
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    limit: 10
    keys: ["title", "permalink", "summary", "content"]

defaultContentLanguage: zh-cn
defaultContentLanguageInSubdir: true

languages:
  zh-cn:
    languageName: "简体中文"
    contentDir: "/content/zh-cn"
    weight: 1
    title: "致之 | zzzhizhi"
    description: "致之的博客"
    params:
      author: "致之"
      label:
        text: "首页"
        icon: "/apple-touch-icon.jpg"
        iconHeight: 35
      
      profileMode:
        enabled: true
        title: "致之"
        subtitle: "写代码是热爱，写到世界充满爱！"
        imageUrl: "/apple-touch-icon.jpg"
        buttons:
          - name: "博客"
            url: "posts"
          - name: "标签"
            url: "tags"
      
      homeInfoParams:
        Title: "你好 👋"
        Content: "欢迎来到我的博客"
      
      socialIcons:
        - name: github
          url: "https://github.com/zzzhizhiw"
        - name: bilibili
          url: "https://space.bilibili.com/437297385"
        - name: email
          url: "mailto:mail@zzzhizhi.top"
        - name: rss
          url: "/zh-cn/index.xml"
      
      editPost:
        URL: "https://github.com/zzzhizhiw/zzzhizhi-blog"
        Text: "编辑"
        appendFilePath: true
    
    menu:
      main:
        - identifier: "search"
          name: "搜索"
          url: "/search"
          weight: 1
        - identifier: "archives"
          name: "归档"
          url: "/archives"
          weight: 2
        - identifier: "categories"
          name: "分类"
          url: "/categories"
          weight: 3
        - identifier: "tags"
          name: "标签"
          url: "/tags"
          weight: 4

  en:
    languageName: "English"
    contentDir: "/content/en"
    weight: 2
    title: "zzzhizhi | 致之"
    description: "zzzhizhi's blog"
    params:
      author: "zzzhizhi"
      label:
        text: "Home"
        icon: "/apple-touch-icon.jpg"
        iconHeight: 35
      
      profileMode:
        enabled: true
        title: "zzzhizhi"
        subtitle: "Coding is love, coding to the world is full of love!"
        imageUrl: "/apple-touch-icon.jpg"
        buttons:
          - name: "Posts"
            url: "posts"
          - name: "Tags"
            url: "tags"
      
      homeInfoParams:
        Title: "Hi there 👋"
        Content: "Welcome to my blog"
      
      socialIcons:
        - name: github
          url: "https://github.com/zzzhizhiw"
        - name: bilibili
          url: "https://space.bilibili.com/437297385"
        - name: email
          url: "mailto:mail@zzzhizhi.top"
        - name: rss
          url: "/en/index.xml"
      
      editPost:
        URL: "https://github.com/zzzhizhiw/zzzhizhi-blog"
        Text: "Edit"
        appendFilePath: true
    
    menu:
      main:
        - identifier: "search"
          name: "Search"
          url: "/search"
          weight: 1
        - identifier: "archives"
          name: "Archives"
          url: "/archives"
          weight: 2
        - identifier: "categories"
          name: "Categories"
          url: "/categories"
          weight: 3
        - identifier: "tags"
          name: "Tags"
          url: "/tags"
          weight: 4

outputs:
  home:
    - HTML
    - RSS
    - JSON

markup:
  highlight:
    noClasses: false
    codeFences: true
    guessSyntax: true
    lineNos: true
    lineNumbersInTable: true
    style: monokai
    
  goldmark:
    renderer:
      unsafe: true
    
  tableOfContents:
    startLevel: 1
    endLevel: 3
    ordered: false

Table of Contents#

Multilingual#

Search#

Fonts#

Code Block Background Color#

Comments#

Deployment#

hugo.yaml Example#

Table of Contents