模塊指南
本頁內容
贊助
想要創建和分享你的創意 HB 模塊嗎？這裏有你想要知道的一切。
示例功能
源碼。
讓我們從 hello 示例開始，其：
- 於
<html>和<body>上追加屬性。 - 使用鉤子以添加自定義 HTML 標記，如元標記、CSS 和 JS。
- 於頁面顯示問候信息，並使用 SCSS、TypeScript 修改其樣式和文本。
準備工作
初始化模塊
首先，創建並初始化一個模塊。
1mkdir hello && cd hello
1git init
1hugo mod init example.com/vendor/hello
請將模塊路徑 example.com/vendor/hello 替換成你的，比如 github.com/hbstack/hello，其中 vendor 爲組織名稱或你的用戶名。
本指南始終使用
example.com/vendor/hello 作爲模塊路徑。設置 HB 站點
推薦於 HB 站點導入本地模塊，以方便開發和調試。
導入本地模塊
首先，我們需要導入本地模塊到 HB 站點。
hugo.toml
1[module]
2 [[module.imports]]
3 path = 'example.com/vendor/hello'
hugo.yaml
1module:
2 imports:
3 - path: example.com/vendor/hello
hugo.json
1{
2 "module": {
3 "imports": [
4 {
5 "path": "example.com/vendor/hello"
6 }
7 ]
8 }
9}
然後於 go.mod 中將其映射到本地路徑。
1replace example.com/vendor/hello => /path/to/hello
其中 /path/to/hello 爲模塊的路徑，相對路徑和絕對路徑都是有效的。
啓動測試站點
1hugo server --gc --disableFastRender
模塊配置文件
回到模塊，創建以下模塊配置文件。
hugo.toml
1[module]
2 [[module.imports]]
3 path = 'github.com/hbstack/hb'
hugo.yaml
1module:
2 imports:
3 - path: github.com/hbstack/hb
hugo.json
1{
2 "module": {
3 "imports": [
4 {
5 "path": "github.com/hbstack/hb"
6 }
7 ]
8 }
9}
其聲明瞭 github.com/hbstack/hb 模塊是必須的。
現在是時候開始實現功能了。
hb-vendor-hello 將作爲 HugoPress 的模塊名稱，我們推薦以相同模式 hb-vendor-name 命名你的模塊，以避免和 HugoPress 模塊以及 HB 內置模塊相沖突。於 <html> 和 <body> 上追加屬性
追加以下配置以添加額外的 HTML 屬性。
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
hugo.yaml
1params:
2 hugopress:
3 modules:
4 hb-vendor-hello:
5 attributes:
6 body:
7 cacheable: true
8 document:
9 cacheable: true
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}
其中 cacheable 表明屬性是否可緩存，若屬性值包含動態內容，則禁用。
然後通過模板定義額外的屬性。
layouts/partials/hugopress/modules/hb-vendor-hello/attributes/document.html
1{{- return dict
2 "data-hello" "document"
3-}}
layouts/partials/hugopress/modules/hb-vendor-hello/attributes/body.html
1{{- return dict
2 "data-hello" "body"
3-}}
若無意外，HTML 源代碼如下所示：
1<html ... data-hello="document" ...>
2 <body ... data-hello="body" ...>
3 </body>
4</html>
使用鉤子
本例子只使用了若干個鉤子，所有可用的鉤子可從文檔和 HugoPress’s 內置鉤子中找到。
請注意，鉤子模板的上下文不同於常規模板，詳情請參閱 hooks context。
於 <head> 上生成內容
有兩個內置的鉤子可用於在 <head> 內放置自定義內容：head-begin 和 head-end，通常用於生成元標記、導入樣式等。
追加以下配置以啓用。
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
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
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}
同屬性，若模板包含動態內容，則禁用
cacheable。
然後創建對應的模板：
layouts/partials/hugopress/modules/hb-vendor-hello/hooks/head-begin.html
1<meta name="hello" content="head-begin">
layouts/partials/hugopress/modules/hb-vendor-hello/hooks/head-end.html
1<meta name="hello" content="head-end">
現在頁面將包含以下元標記。
1<head>
2 <meta name="hello" content="head-begin">
3 <meta name="hello" content="head-end">
4</head>
顯示問候語
最後，於頁面頂部顯示一則問候語。
配置如下：
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
hugo.yaml
1params:
2 hugopress:
3 modules:
4 hb-vendor-hello:
5 hooks:
6 body-begin:
7 cacheable: true
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}
layouts/partials/hugopress/modules/hb-vendor-hello/hooks/body-begin.html
1<div class="hb-vendor-hello text-center">Hello!</div>
如無意外，該問候語將顯示與頁面頂部。
添加樣式
你也許希望添加樣式以美化頁面，以問候語爲例，我們修改其背景色和顏色。
爲了實現模塊的靈活性，我們定義了以下參數。
hugo.toml
1[params]
2 [params.hb]
3 [params.hb.vendor_hello]
4 bg = 'blue'
5 color = 'white'
hugo.yaml
1params:
2 hb:
3 vendor_hello:
4 bg: blue
5 color: white
hugo.json
1{
2 "params": {
3 "hb": {
4 "vendor_hello": {
5 "bg": "blue",
6 "color": "white"
7 }
8 }
9 }
10}
接着創建以下 SCSS 文件。
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 }};
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 */
重啓 Hugo 服務器以確保完全加載 SCSS 文件。
添加腳本
最後，讓我們利用 JS 修改問候語。
hugo.toml
1[params]
2 [params.hb]
3 [params.hb.vendor_hello]
4 message = 'Hello world!'
hugo.yaml
1params:
2 hb:
3 vendor_hello:
4 message: Hello world!
hugo.json
1{
2 "params": {
3 "hb": {
4 "vendor_hello": {
5 "message": "Hello world!"
6 }
7 }
8 }
9}
assets/hb/modules/vendor-hello/js/index.ts
1import * as params from '@params'
2
3document.querySelector('.hb-vendor-hello').innerText = params.vendor_hello.message
於生產模式下測試
腳本使用到的樣式會被 PurgeCSS 移除，詳情請參閱 PurgeCSS。
PurgeCSS 只有在生產模式下生效，我們可以通過以下命令於生產模式預覽模塊。
1hugo server -e production --minify --gc --renderToDisk -b http://localhost:1313 -p 1313
發佈
當模塊完成後，是時候通過推送到遠程倉庫以發佈模塊了，然後將映射關係從 go.mod 中移除。
