Prerequisites
HB is a feature-rich framework, but it also has a certain complexity. This article will detail the requirements for HB so that you can develop and use HB modules and themes properly.
Required Configurations§
hugo.toml
1[build]
2 writeStats = true
tomlhugo.yaml
1build:
2 writeStats: true
yamlhugo.json
1{
2 "build": {
3 "writeStats": true
4 }
5}
jsonUsed to collect used CSS, such as classes, ids and tags, which will be used to purging unused CSS.
Build Tools§
It’s recommended using the latest version of those tools as possible.
Go§
HB is a modular framework, requires Go installation to download and upgrade Hugo Modules.
1sudo pacman -S go
shHugo§
HB uses Hugo Pipes to compile SCSS, so an extended version of Hugo is required.
If you’re located in China mainland without VPN, you’ll need to set up the Go proxy first.
1go install -tags extended github.com/gohugoio/hugo@latest
shGit§
The version control system, can be fetched on the downloads page.
1sudo pacman -S git
shNode.js§
Requires Node.js
16or later.
HB requires the following Node.js packages.
1sudo pacman -S nodejs
sh| Name | Description |
|---|---|
| PostCSS CLI | Transform styles. |
| RTLCSS | Convert LTR CSS to RTL, optional if you don’t have RTL sites. |
| Autoprefixer | Parse CSS and add vendor prefixes to rules by Can I Use. |
| PurgeCSS | Remove unused CSS. |
NPM has been included in the Node.js installation, you can either install those packages locally or globally.
1npm i -D postcss-cli @fullhuman/postcss-purgecss autoprefixer rtlcss
shThis approach writes dependencies to package.json, so that those packages can be installed via npm i without having to remember the complicated package names.
1sudo npm i -g postcss-cli @fullhuman/postcss-purgecss autoprefixer rtlcss
shThis command needs to be executed only once and does not need to be executed again for subsequent HB sites.
Both are valid, HB will try to look up the packages locally first.
Notes§
publishDir MUST be public
publishDir MUST be publicIt’s limited by the HB implementation about sharing PurgeCSS configurations.
This limitation was fixed in v0.7.2.
Required Parameters for Hugo Server Production Mode§
If you need to use Hugo Server in production mode, you need to specify --disableFastRender and --renderToDisk, otherwise PurgeCSS and PostCSS will have unexpected problems.
1hugo server \
2 --disableFastRender \
3 --renderToDisk \
4 -e production \
5 -b http://localhost:1314 \
6 -p 1314
shPlease Do Not Changing hb and hugopress Parameters via Language-Scoped Configurations§
HB relies on deep merging of configurations between modules, however language-scoped parameters will override the configuration of overriding modules rather than deep merging, which will lead to all sorts of unexpected problems. For example, the following configuration example is not allowed.
hugo.toml
1[language]
2 [language.en]
3 [language.en.params]
4 [language.en.params.hb]
5 foo = 'bar'
6 [language.en.params.hugopress]
7 foo = 'bar'
8 [language.zh-hans]
9 [language.zh-hans.params]
10 [language.zh-hans.params.hb]
11 foo = 'bar'
12 [language.zh-hans.params.hugopress]
13 foo = 'bar'
tomlhugo.yaml
1language:
2 en:
3 params:
4 hb:
5 foo: bar
6 hugopress:
7 foo: bar
8 zh-hans:
9 params:
10 hb:
11 foo: bar
12 hugopress:
13 foo: bar
yamlhugo.json
1{
2 "language": {
3 "en": {
4 "params": {
5 "hb": {
6 "foo": "bar"
7 },
8 "hugopress": {
9 "foo": "bar"
10 }
11 }
12 },
13 "zh-hans": {
14 "params": {
15 "hb": {
16 "foo": "bar"
17 },
18 "hugopress": {
19 "foo": "bar"
20 }
21 }
22 }
23 }
24}
jsonPlease Disable Cloudflare Rocket Loader§
Cloudflare Rocket Loader missing the DOMContentLoaded event, will cause many modules to fail, even if we provide a patch for this, but the loss outweighs the gain, disable the feature is the best choice for now.