想要创建和分享你的创意 HB 模块吗?这里有你想要知道的一切。
源码。
让我们从 hello
示例开始,其:
<html>
和 <body>
上追加属性。首先,创建并初始化一个模块。
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 站点。
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
表明属性是否可缓存,若属性值包含动态内容,则禁用。
然后通过模板定义额外的属性。
1{{- return dict
2 "data-hello" "document"
3-}}
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
。
然后创建对应的模板:
1<meta name="hello" content="head-begin">
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}
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 文件。
1$hb-vendor-hello-bg: {{ default "blue" .params.hb.vendor_hello.bg }};
2$hb-vendor-hello-color: {{ default "white" .params.hb.vendor_hello.color }};
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}
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
中移除。