Module Guide

Do you want to create and share your creative HB modules? Here is everything you want to know.

Example Functionalities§

Source code.

Let’s get started with a hello example, which:

  • Appends attributes on <html> and <body>.
  • Using hooks to include custom HTML markup, such as meta tags, CSS and JS.
  • Generates greeting messages on HTML pages, and style/modify it with SCSS/TypeScript.

Preparations§

  • An HB site for testing your module, you could use the starter theme if you don’t have one yet.
  • Familiar with Hugo development.
  • Build tools installations.

Initial Module§

First of all, create and initial a module.

1mkdir hello && cd hello
sh
1git init
sh
1hugo mod init example.com/vendor/hello
sh

Replace the module path example.com/vendor/hello as your own, such as github.com/hbstack/hello, the vendor is your organization name or username.

Set up a HB Site§

It’s recommended importing the local module into your HB site for developing.

Import the Local Module§

Firstly, we need to import the local hello module into site’s configuration:

hugo.toml

1[module]
2[[module.imports]]
3    path = 'example.com/vendor/hello'
toml

hugo.yaml

1module:
2  imports:
3  - path: example.com/vendor/hello
yaml

hugo.json

1{
2   "module": {
3      "imports": [
4         {
5            "path": "example.com/vendor/hello"
6         }
7      ]
8   }
9}
json

And then mapping the module to local path in site’s go.mod.

1replace example.com/vendor/hello => /path/to/hello
go

The /path/to/hello is the file path of the hello module, both of relative path and absolute path are valid.

Start the Testing Site§

1hugo server --gc --disableFastRender
sh

Module Configuration File§

Back to the module, create a module configuration file.

hugo.toml

1[module]
2[[module.imports]]
3    path = 'github.com/hbstack/hb'
toml

hugo.yaml

1module:
2  imports:
3  - path: github.com/hbstack/hb
yaml

hugo.json

1{
2   "module": {
3      "imports": [
4         {
5            "path": "github.com/hbstack/hb"
6         }
7      ]
8   }
9}
json

It declared that the github.com/hbstack/hb module is required.

It’s time to start implementing the functionalities.

Append Attributes on <html> and <body>§

To add additional HTML attributes by appending the following configuration.

hugo.toml

1[params]
2  [params.hugopress]
3    [params.hugopress.modules]
4      [params.hugopress.modules.hb-vendor-hello]
5        [params.hugopress.modules.hb-vendor-hello.attributes]
6          [params.hugopress.modules.hb-vendor-hello.attributes.body]
7            cacheable = true
8          [params.hugopress.modules.hb-vendor-hello.attributes.document]
9            cacheable = true
toml

hugo.yaml

1params:
2  hugopress:
3    modules:
4      hb-vendor-hello:
5        attributes:
6          body:
7            cacheable: true
8          document:
9            cacheable: true
yaml

hugo.json

 1{
 2   "params": {
 3      "hugopress": {
 4         "modules": {
 5            "hb-vendor-hello": {
 6               "attributes": {
 7                  "body": {
 8                     "cacheable": true
 9                  },
10                  "document": {
11                     "cacheable": true
12                  }
13               }
14            }
15         }
16      }
17   }
18}
json

The cacheable flag caches the attributes to improve the build performance, disable it if the attributes contain dynamic data.

And then define the additional attributes via partials.

layouts/partials/hugopress/modules/hb-vendor-hello/attributes/document.html
1{{- return dict
2  "data-hello" "document"
3-}}
go-html-template
layouts/partials/hugopress/modules/hb-vendor-hello/attributes/body.html
1{{- return dict
2  "data-hello" "body"
3-}}
go-html-template

If everything is OK, the HTML source code looks like follows:

1<html ... data-hello="document" ...>
2  <body ... data-hello="body" ...>
3  </body>
4</html>
html

Using Hooks§

This example uses only a few hooks, all available hooks could be found on our docs and HugoPress’s built-in hooks.

Please note that the context of hook partials is different than regular partial, see hooks context.

Generate Stuff on <head>§

There are two built-in hooks for putting custom stuff on <head>: head-begin and head-end, which used to generate meta tags, include stylesheet and so on.

Append the following configuration to enable it.

hugo.toml

1[params]
2  [params.hugopress]
3    [params.hugopress.modules]
4      [params.hugopress.modules.hb-vendor-hello]
5        [params.hugopress.modules.hb-vendor-hello.hooks]
6          [params.hugopress.modules.hb-vendor-hello.hooks.head-begin]
7            cacheable = true
8          [params.hugopress.modules.hb-vendor-hello.hooks.head-end]
9            cacheable = true
toml

hugo.yaml

1params:
2  hugopress:
3    modules:
4      hb-vendor-hello:
5        hooks:
6          head-begin:
7            cacheable: true
8          head-end:
9            cacheable: true
yaml

hugo.json

 1{
 2   "params": {
 3      "hugopress": {
 4         "modules": {
 5            "hb-vendor-hello": {
 6               "hooks": {
 7                  "head-begin": {
 8                     "cacheable": true
 9                  },
10                  "head-end": {
11                     "cacheable": true
12                  }
13               }
14            }
15         }
16      }
17   }
18}
json

Same as attributes, disable the cacheable if the template contains dynamic data.

And then create the corresponding templates.

layouts/partials/hugopress/modules/hb-vendor-hello/hooks/head-begin.html
1<meta name="hello" content="head-begin">
go-html-template
layouts/partials/hugopress/modules/hb-vendor-hello/hooks/head-end.html
1<meta name="hello" content="head-end">
go-html-template

Now the pages have the following meta tags.

1<head>
2  <meta name="hello" content="head-begin">
3  <meta name="hello" content="head-end">
4</head>
html

Generates the Greeting Message§

Finally, create greeting messages on the top of pages.

Configuration as following.

hugo.toml

1[params]
2  [params.hugopress]
3    [params.hugopress.modules]
4      [params.hugopress.modules.hb-vendor-hello]
5        [params.hugopress.modules.hb-vendor-hello.hooks]
6          [params.hugopress.modules.hb-vendor-hello.hooks.body-begin]
7            cacheable = true
toml

hugo.yaml

1params:
2  hugopress:
3    modules:
4      hb-vendor-hello:
5        hooks:
6          body-begin:
7            cacheable: true
yaml

hugo.json

 1{
 2   "params": {
 3      "hugopress": {
 4         "modules": {
 5            "hb-vendor-hello": {
 6               "hooks": {
 7                  "body-begin": {
 8                     "cacheable": true
 9                  }
10               }
11            }
12         }
13      }
14   }
15}
json
layouts/partials/hugopress/modules/hb-vendor-hello/hooks/body-begin.html
1<div class="hb-vendor-hello text-center">Hello!</div>
go-html-template

Now the greeting message will be shown on the top of pages.

Styling Module§

You may want to beautify the HTML generated by module with styles, let’s take the greeting message as an example that change the background and color.

To make module flexible, we declare parameters for those styles.

hugo.toml

1[params]
2  [params.hb]
3    [params.hb.vendor_hello]
4      bg = 'blue'
5      color = 'white'
toml

hugo.yaml

1params:
2  hb:
3    vendor_hello:
4      bg: blue
5      color: white
yaml

hugo.json

 1{
 2   "params": {
 3      "hb": {
 4         "vendor_hello": {
 5            "bg": "blue",
 6            "color": "white"
 7         }
 8      }
 9   }
10}
json

And then create the SCSS files.

assets/hb/modules/vendor-hello/scss/variables.tmpl.scss
1$hb-vendor-hello-bg: {{ default "blue" .params.hb.vendor_hello.bg }};
2$hb-vendor-hello-color: {{ default "white" .params.hb.vendor_hello.color }};
scss
assets/hb/modules/vendor-hello/scss/index.scss
1/* purgecss start ignore */
2
3.hb-vendor-hello {
4    background: $hb-vendor-hello-bg;
5    color: $hb-vendor-hello-color;
6}
7
8/* purgecss end ignore */
scss

Restart the Hugo server to ensure loading the SCSS files fully.

Adding Scripts§

Finally, let’s modify the greeting message in JS way.

hugo.toml

1[params]
2  [params.hb]
3    [params.hb.vendor_hello]
4      message = 'Hello world!'
toml

hugo.yaml

1params:
2  hb:
3    vendor_hello:
4      message: Hello world!
yaml

hugo.json

1{
2   "params": {
3      "hb": {
4         "vendor_hello": {
5            "message": "Hello world!"
6         }
7      }
8   }
9}
json
assets/hb/modules/vendor-hello/js/index.ts
1import * as params from '@params'
2
3document.querySelector('.hb-vendor-hello').innerText = params.vendor_hello.message
ts

Test on Production Mode§

The styles used by JavaScript will be removed by PurgeCSS, please checkout the PurgeCSS section for details.

The PurgeCSS gets processed on production mode only, we could preview the module on production mode via:

1hugo server -e production --minify --gc --renderToDisk -b http://localhost:1313 -p 1313
sh

Deployment§

Once the module is done, it’s time to publish it by pushing it to your git providers, and then remove the mapping from go.mod.

  • All
  • English
  • 简体中文
  • 繁體中文
  • Best match
  • Oldest
  • Newest
  • 2020
  • 2022
  • 2023
  • HB Framework Authors
  • Hugo Authors
  • Banner
  • Build Tools
  • Comments
  • Configuration
  • Deployment
  • Develop
  • Footer
  • Header
  • Inline Frame
  • Installation
  • Look and Feel
  • Menus
  • Module
  • Modules
  • Shortcode
  • Sidebar
  • 侧边栏
  • 内容
  • 安装
  • 开发
  • 构建工具
  • 概览
  • 模块
  • 横幅
  • 短代码
  • 菜单
  • 观感
  • 评论
  • 部署
  • 配置
  • 页头
  • 页尾
  • 側邊欄
  • 內容
  • 安裝
  • 概覽
  • 構建工具
  • 模塊
  • 橫幅
  • 短代碼
  • 菜單
  • 觀感
  • 評論
  • 開發
  • 頁尾
  • 頁頭
  • Docs
  • Examples
  • Modules
  • News
  • Showcases
  • Themes
  • Tutorials
  • 教程
  • 文档
  • 新闻
  • 模块
  • 示例
  • 文檔
  • 新聞
  • 模塊
  • Alert
  • Animations
  • AOS
  • Applications
  • asciinema
  • Authors
  • Autoprefixer
  • Back to top
  • Background Image
  • beian
  • Bigger Picture
  • Bilibili
  • Blog
  • Bootstrap
  • Breadcrumb
  • Breakpoint
  • Classic
  • clean
  • Clearfix
  • Cloudflare Pages
  • Code Block Panel
  • CodePen
  • Comments
  • Comments Engine
  • Config Toggle
  • Contact
  • Contact Form
  • Content Panel
  • CSS
  • Dark Mode
  • defaultContentLanguageInSubdir
  • Diagrams
  • Disqus
  • Docker
  • Docs
  • DocSearch
  • Domain
  • Featured Image
  • Figure
  • Fonts
  • Footer
  • Footer Menus
  • frame
  • Gallery
  • GCSE
  • Giscus
  • Gist
  • Git
  • GitHub Pages
  • Go
  • Google
  • Google Fonts
  • graph
  • Header
  • Header Menus
  • Heading Sign
  • Highlight
  • HLS
  • Hooks
  • HTML
  • Hugo
  • Icon
  • iframe
  • Image
  • Image Link
  • Instagram
  • Introduction
  • JavaScript
  • JS
  • JSRun
  • KaTex
  • Language Picker
  • Lead
  • Light Mode
  • Markdown
  • Menus
  • Mermaid
  • Meta
  • Module
  • MPD
  • MPEG-DASH
  • Multilingual
  • NetEase Could Music
  • Netlify
  • News
  • Node.js
  • noscript
  • NPM
  • Pagination
  • Param
  • Picture
  • Pills
  • PostCSS
  • Posts
  • Profile
  • Progress Bar
  • PurgeCSS
  • PWA
  • Ratio
  • ref
  • Related Posts
  • relref
  • Return to top
  • RTLCSS
  • Scrollbar
  • Scrollspy
  • SCSS
  • Search
  • Search Engines
  • Slide
  • Social Links
  • Socials
  • Start Page
  • Staticman
  • Style Guide
  • Syntax Highlighting
  • Table of Contents
  • Taxonomies
  • Theme
  • Themes
  • tidy
  • ToC
  • Toggle
  • Tweet
  • Twikoo
  • TypeScript
  • Utterances
  • Videos
  • Vimeo
  • YouKu
  • YouTube
  • Front Matter
  • JSON
  • TOML
  • YAML
  • 主题
  • 代码块面板
  • 优酷
  • 作者
  • 元模块
  • 公告栏
  • 内容面板
  • 内容面板模块
  • 分类
  • 分页
  • 动画
  • 博客
  • 哔哩哔哩
  • 回到顶部
  • 图库
  • 图标
  • 图片
  • 图片链接
  • 图表
  • 域名
  • 备案
  • 多语言
  • 字体
  • 幻灯片
  • 搜索
  • 文档
  • 文章
  • 断点
  • 新闻
  • 标题链接
  • 浅色模式
  • 深色模式
  • 滚动条
  • 特色图片
  • 目录
  • 相关文章
  • 社交链接
  • 简介
  • 网易云音乐
  • 联系表单
  • 背景图片
  • 菜单
  • 视频
  • 评论
  • 评论引擎
  • 语法高亮
  • 语言选项
  • 谷歌
  • 谷歌字体
  • 返回顶部
  • 进度条
  • 钩子
  • 面包屑导航
  • 页头
  • 页头菜单
  • 页尾
  • 页尾菜单
  • 风格指南
  • 主題
  • 代碼塊面板
  • 備案
  • 優酷
  • 元模塊
  • 內容面板
  • 內容面板模塊
  • 公告欄
  • 分頁
  • 分類
  • 動畫
  • 嗶哩嗶哩
  • 回到頂部
  • 圖庫
  • 圖標
  • 圖片
  • 圖片鏈接
  • 圖表
  • 多語言
  • 字體
  • 幻燈片
  • 文檔
  • 新聞
  • 斷點
  • 標題鏈接
  • 淺色模式
  • 滾動條
  • 特色圖片
  • 目錄
  • 相關文章
  • 社交鏈接
  • 簡介
  • 網易雲音樂
  • 聯繫表單
  • 背景圖片
  • 菜單
  • 視頻
  • 評論
  • 評論引擎
  • 語法高亮
  • 語言選項
  • 谷歌字體
  • 返回頂部
  • 進度條
  • 鉤子
  • 頁尾
  • 頁尾菜單
  • 頁頭
  • 頁頭菜單
  • 風格指南
  • 麪包屑導航