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

hugo.yaml

1build:
2  writeStats: true

hugo.json

1{
2   "build": {
3      "writeStats": true
4   }
5}
build.writeStats
Used 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

Hugo

Version

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 target="_blank" rel=“noopener noreferrer”>Go proxy first.

1go install -tags extended github.com/gohugoio/hugo@latest

Git

The version control system, can be fetched on the downloads page.

1sudo pacman -S git

Node.js

Requires Node.js 16 or later.

HB requires the following Node.js packages.

1sudo pacman -S nodejs
NameDescription
PostCSS CLITransform styles.
RTLCSSConvert LTR CSS to RTL, optional if you don’t have RTL sites.
AutoprefixerParse CSS and add vendor prefixes to rules by Can I Use.
PurgeCSSRemove unused CSS.

NPM has been included in the Node.js installation, you can either install those packages locally or globally.

Install Locally
1npm i -D postcss-cli @fullhuman/postcss-purgecss autoprefixer rtlcss

This approach writes dependencies to package.json, so that those packages can be installed via npm i without having to remember the complicated package names.

Install Globally
1sudo npm i -g postcss-cli @fullhuman/postcss-purgecss autoprefixer rtlcss

This 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

It’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

Please 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'

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

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

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