模塊指南

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

示例功能§

源碼

讓我們從 hello 示例開始,其:

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

準備工作§

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

初始化模塊§

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

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

請將模塊路徑 example.com/vendor/hello 替換成你的,比如 github.com/hbstack/hello,其中 vendor 爲組織名稱或你的用戶名。

設置 HB 站點§

推薦於 HB 站點導入本地模塊,以方便開發和調試。

導入本地模塊§

首先,我們需要導入本地模塊到 HB 站點。

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

然後於 go.mod 中將其映射到本地路徑。

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

其中 /path/to/hello 爲模塊的路徑,相對路徑和絕對路徑都是有效的。

啓動測試站點§

1hugo server --gc --disableFastRender
sh

模塊配置文件§

回到模塊,創建以下模塊配置文件。

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

其聲明瞭 github.com/hbstack/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
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

其中 cacheable 表明屬性是否可緩存,若屬性值包含動態內容,則禁用。

然後通過模板定義額外的屬性。

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

若無意外,HTML 源代碼如下所示:

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

使用鉤子§

本例子只使用了若干個鉤子,所有可用的鉤子可從文檔和 HugoPress’s 內置鉤子中找到。

請注意,鉤子模板的上下文不同於常規模板,詳情請參閱 hooks context

<head> 上生成內容§

有兩個內置的鉤子可用於在 <head> 內放置自定義內容:head-beginhead-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
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

同屬性,若模板包含動態內容,則禁用 cacheable

然後創建對應的模板:

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

現在頁面將包含以下元標記。

1<head>
2  <meta name="hello" content="head-begin">
3  <meta name="hello" content="head-end">
4</head>
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.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

如無意外,該問候語將顯示與頁面頂部。

添加樣式§

你也許希望添加樣式以美化頁面,以問候語爲例,我們修改其背景色和顏色。

爲了實現模塊的靈活性,我們定義了以下參數。

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

接着創建以下 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 }};
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

重啓 Hugo 服務器以確保完全加載 SCSS 文件。

添加腳本§

最後,讓我們利用 JS 修改問候語。

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

於生產模式下測試§

腳本使用到的樣式會被 PurgeCSS 移除,詳情請參閱 PurgeCSS

PurgeCSS 只有在生產模式下生效,我們可以通過以下命令於生產模式預覽模塊。

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

發佈§

當模塊完成後,是時候通過推送到遠程倉庫以發佈模塊了,然後將映射關係從 go.mod 中移除。

  • 全部
  • English
  • 简体中文
  • 繁體中文
  • 最佳匹配
  • 最舊的
  • 最新的
  • 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
  • 主题
  • 代码块面板
  • 优酷
  • 作者
  • 元模块
  • 公告栏
  • 内容面板
  • 内容面板模块
  • 分类
  • 分页
  • 动画
  • 博客
  • 哔哩哔哩
  • 回到顶部
  • 图库
  • 图标
  • 图片
  • 图片链接
  • 图表
  • 域名
  • 备案
  • 多语言
  • 字体
  • 幻灯片
  • 搜索
  • 文档
  • 文章
  • 断点
  • 新闻
  • 标题链接
  • 浅色模式
  • 深色模式
  • 滚动条
  • 特色图片
  • 目录
  • 相关文章
  • 社交链接
  • 简介
  • 网易云音乐
  • 联系表单
  • 背景图片
  • 菜单
  • 视频
  • 评论
  • 评论引擎
  • 语法高亮
  • 语言选项
  • 谷歌
  • 谷歌字体
  • 返回顶部
  • 进度条
  • 钩子
  • 面包屑导航
  • 页头
  • 页头菜单
  • 页尾
  • 页尾菜单
  • 风格指南
  • 主題
  • 代碼塊面板
  • 備案
  • 優酷
  • 元模塊
  • 內容面板
  • 內容面板模塊
  • 公告欄
  • 分頁
  • 分類
  • 動畫
  • 嗶哩嗶哩
  • 回到頂部
  • 圖庫
  • 圖標
  • 圖片
  • 圖片鏈接
  • 圖表
  • 多語言
  • 字體
  • 幻燈片
  • 文檔
  • 新聞
  • 斷點
  • 標題鏈接
  • 淺色模式
  • 滾動條
  • 特色圖片
  • 目錄
  • 相關文章
  • 社交鏈接
  • 簡介
  • 網易雲音樂
  • 聯繫表單
  • 背景圖片
  • 菜單
  • 視頻
  • 評論
  • 評論引擎
  • 語法高亮
  • 語言選項
  • 谷歌字體
  • 返回頂部
  • 進度條
  • 鉤子
  • 頁尾
  • 頁尾菜單
  • 頁頭
  • 頁頭菜單
  • 風格指南
  • 麪包屑導航