Prerequisites

Required Configurations

1[build]
2  writeStats = true

1build:
2  writeStats: true

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

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

Dart Sass

See Install Dart Sass.

Hugo

HB uses Hugo Pipes to compile SCSS, so an extended version of Hugo is required.

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

We offered a meta package @hbstack/node-packages that includes all required packages.

1npm i @hbstack/node-packages

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.

 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'

 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

 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.