模塊指南

2023年2月16日 4 分鐘閱讀開發文檔文檔 SCSS Hooks TypeScript JavaScript CSS

本頁內容

想要創建和分享你的創意 HB 模塊嗎？這裏有你想要知道的一切。

示例功能

源碼。

讓我們從 hello 示例開始，其：

於 <html> 和 <body> 上追加屬性。
使用鉤子以添加自定義 HTML 標記，如元標記、CSS 和 JS。
於頁面顯示問候信息，並使用 SCSS、TypeScript 修改其樣式和文本。

準備工作

一個用於模塊測試的 HB 站點，如果還沒有，可以使用入門主題。
熟悉雨果開發。
已安裝好構建工具。

初始化模塊

首先，創建並初始化一個模塊。

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 中移除。

PurgeCSS

瀏覽文檔

模塊指南

示例功能

準備工作

初始化模塊

設置 HB 站點

導入本地模塊

啓動測試站點

模塊配置文件

於 <html> 和 <body> 上追加屬性

使用鉤子

於 <head> 上生成內容

顯示問候語

添加樣式

添加腳本

於生產模式下測試

發佈

於 `<html>` 和 `<body>` 上追加屬性

於 `<head>` 上生成內容