Modules Principle

This article describes the structure of the module, its principles and some development conventions.

Structure

 1├── assets
 2│   └── hb
 3│       └── modules
 4│           └── vendor-name
 5│               ├── js
 6│               │   └── index.ts
 7│               └── scss
 8│                   ├── index.scss
 9│                   └── variables.tmpl.scss
10├── go.mod
11├── hugo.toml
12├── i18n
13├── layouts
14    └── partials
15        └── hugopress
16            └── modules
17                └── hb-vendor-name
18                    ├── attributes
19                    │   └── ...
20                    └── hooks
21                        └── ...
22└── ...

HB will:

  • Loads SCSS variables from scss/variables.tmpl.scss, and then loads and compiles scss/index.scss into the CSS bundle.
  • Loads and compiles the js/index.ts into the JS bundle.
  • The purgecss.config.toml used to add styles to PurgeCSS safelist, in order to avoid getting removing.

SCSS

SCSS Variables

The scss/variables.tmpl.scss is a template that used to define SCSS variables, which allow using Hugo template syntaxes, such as reading parameters from Hugo configuration.

SCSS Entry

The scss/index.scss will be imported and compiled into the CSS bundle, you’re able to use the variables defined above.

TypeScript

The js/index.ts will be imported and compiled into the JavaScript bundle.

PurgeCSS

The purgecss.config.toml used to append styles to PurgeCSS safelist, in order to avoid getting removing on production environment.

Convertions

Module Naming Convention

We strongly recommend naming your HB module in form: vendor-name, in order to avoid conflicting with HB built-in modules.

  • vendor: your name or organization name.
  • name: the module name.

See also creating a module.

Module Parameters Naming Convention

Since Hugo configuration are case-insensitive, it’s recommended to name parameters in snake_case. In addition to this, there is a need to categorize parameters by their module names.

Let’s said there is a third party module called razonyang-hello, it’s parameters should look like the follows.

hugo.toml

1[params]
2  [params.hb]
3    [params.hb.razonyang_hello]
4      foo = 'bar'

hugo.yaml

1params:
2  hb:
3    razonyang_hello:
4      foo: bar

hugo.json

1{
2   "params": {
3      "hb": {
4         "razonyang_hello": {
5            "foo": "bar"
6         }
7      }
8   }
9}
razonyang
Sunday, November 3, 2024 Thursday, April 25, 2024