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


2  writeStats = true


2  writeStats: true


2   "build": {
3      "writeStats": true
4   }

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.


HB is a modular framework, requires Go installation to download and upgrade Hugo Modules.

1sudo pacman -S go



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


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

1sudo pacman -S git


Requires Node.js 16 or later.

HB requires the following Node.js packages.

1sudo pacman -S nodejs
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.


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.


 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'


 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


 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   }

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.