Hugo Custom Fonts

This blog is currently powered by Hugo and the hugo-clarity skin, which works fine. However, the default font for this theme is Metropolis, which the operating system doesn't have by default, requiring users to download it. This slows down page loading. The default Chinese font falls back to sans-serif, which isn't a good solution. Therefore, I need to customize the font for this skin.

1. First, find the font and modify the configuration.

The font configuration control file for the hugo-clarity skin is shown above. The CSS is generated using Sass. Here's how to modify it:

• _fonts.sass Configuration

1@font-face
2font-family: myfonts
3src: local('-apple-system'),local('BlinkMacSystemFont'),local('Helvetica Neue'),local('PingFang SC'),local('Microsoft YaHei'),local('Source Han Sans SC'),local('Noto Sans CJK SC'),local('WenQuanYi Micro Hei'),local('sans-serif')

This file tells you where to find the font files. local('xxx') means to search locally on your computer for xxx Fonts. Name these font collections myfonts. You can choose your own name, using the font-face syntax. I used the font-family from Zhihu as a reference:

1font-family: -apple-system, BlinkMacSystemFont, Helvetica Neue, PingFang SC,
2Microsoft YaHei, Source Han Sans SC, Noto Sans CJK SC, WenQuanYi Micro Hei,
3sans-serif;

In descending order of priority, search for Apple's default fonts first, then Windows fonts, Sans, and other fonts, and finally for Linux's WenQuanYi Micro Hei. Depending on the user's operating system, system-provided fonts will be prioritized, eliminating the need to consume network bandwidth and slow down web page loading.

• _variables.sass Configuration

Set up the variables file. Fill in the font family name from the previous step in the --font section, as shown in the image. This will allow the Sass CSS preprocessor to generate the correct font family during compilation.

• fonts Directory

This directory is for custom fonts used in skins. Use it when you have high font requirements (I personally don't use it). Refer to the hugo-clarity skin's configuration

1@font-face
2font-family: 'Metropolis'
3font-style: normal
4font-weight: 200
5src: local('Metropolis Extra Light'), local('Metropolis-Light'), url('#{$fontsPath}Metropolis-ExtraLight.woff2') format('woff2'), url('#{$fontsPath}Metropolis-ExtraLight.woff') format('woff')
6font-display: swap

The above configuration means that the font is first searched on the local computer. If it can't be found, it will search the project's font directory (the fonts directory in the first image). Once found, it will perform some format conversion. There are articles online explaining how to change fonts for other skins, so I won't go into detail here; the principles are similar.

2. Recompile the Project

I'd like to note that if you're using the standard version of Hugo, it won't transpile Sass to CSS for you. The official explanation is as follows:

Hugo is available in two editions: standard and extended. With the extended edition, you can:

• 1. Encode WebP images (you can decode WebP images with both editions)
• 2. Transpile Sass to CSS using the embedded LibSass transpiler

We recommend that you install the extended edition.

I didn't notice this at first, and the generated style files were always unchanged, which made all the painful debugging ineffective. Finally, I deleted all the relevant files and tried again. Only then did Hugo prompt me to download the extended version during compilation. This delayed me for nearly two hours, and I even had to learn Sass syntax...

So, I'll definitely use the extended version from now on. It's a painful experience.

3. Code Font

Finally, Hugo's programming font is configurable. The English font used in this article differs from the text in the code. You can see the difference by looking at the letter G.

 1[highlight]
 2codeFences = true
 3guessSyntax = true
 4hl_Lines = ""
 5lineNoStart = 1
 6lineNos = true # always set to true # else line numbers won't show at all! even when toggling them on in the UI
 7lineNumbersInTable = false # toggling this on (i.e., to true) or deleting this line will break the code blocks functionality. Will
 8noClasses = false
 9style = "monokai"
10tabWidth = 2

As shown above, with monokai selected for highlighting mode, the code and pre lines in _syntax.sass are:

1font-family: "Monaco", monospace;

This way, when selecting different code highlighting modes, you can manually set different code fonts as needed (testing with the font change from monokai to tango did not change).