Become a backer or sponsor to support our work.
Pluggable and UI less Hugo modules framework, which defines several functions and partials to load and render Hugo modules automatically. The main advantage is that once the theme support HugoPress, their users have the ability to install the modules without requesting new features to the theme.
Module |
---|
github.com/hugomods/hugopress |
An HTML page is composed of a number of HTML markup blocks.
flowchart TD blocks---BS subgraph html HS[HTML begin] --> blocks[/Render blocks/] blocks --> HE[HTML end] end subgraph block BS[Start] --> attrs[/Render attributes/] attrs --> hooks[/Render hooks/] hooks --> BE[End] end
There are two key concepts: attributes
and hooks
.
The attributes
are used to append attributes to HTML tags.
Name | Description |
---|---|
document | The attributes will be appended into the <html> tag. |
body | The attributes will be appended into the <body> tag. |
The attributes partial should return key-value pairs.
1{{- return dict
2 "lang" .Page.Lang
3 "data-foo" "bar"
4 "data-hello" "world"
5}}
Name | Type | Default | Description |
---|---|---|---|
cacheable | Boolean | false | Whether to cache the attributes. |
The context (aka the .
) of attributes’ partial.
Name | Type | Description |
---|---|---|
Page | Page | Current page. |
The hooks
are used to render HTML of the module in a specific place, such as <head>
, <body>
.
Name | Description |
---|---|
head-begin | At the beginning of the <head> tag. |
head-end | Before the <head> end. |
body-begin | At the beginning of the <body> tag. |
body-end | Before the <body> end. |
Name | Type | Default | Description |
---|---|---|---|
cacheable | Boolean | false | Whether to cache the hooks. |
The context (aka the .
) of hook partial.
Name | Type | Description |
---|---|---|
Total | Number | The number of modules in the current hook. |
Index | Number | The index number of current module. |
HasPrev | Boolean | Whether there are modules(s) before the current. |
HasNext | Boolean | Whether there are modules(s) after the current. |
Page | Page | Current page. |
Modify your baseof.html
as following for getting much more flexible, and then override the theme
blocks.
1{{/* layouts/_default/baseof.html */}}
2<!DOCTYPE html>
3<html {{ partial "hugopress/document-attributes" . | safeHTMLAttr -}}>
4 <head>
5 {{- partial "hugopress/head-begin.html" . }}
6 {{/* Theme head block begin. */}}
7 <title>{{- block "title" . -}}{{ .Title }}{{- end -}}</title>
8 {{/* Theme head block end. */}}
9 {{- partial "hugopress/head-end.html" . }}
10 </head>
11 <body {{ partial "hugopress/body-attributes" . | safeHTMLAttr -}}>
12 {{- partial "hugopress/body-begin.html" . }}
13 {{/* Theme body block begin. */}}
14 {{- block "main" . }}{{- end }}
15 {{/* Theme body block end. */}}
16 {{- partial "hugopress/body-end.html" . }}
17 </body>
18</html>
Let’s take the hello
module as an example, which
data-hello="world"
into the <html>
tag.<meta name="hello" content="world">
inside the <head>
tag.Hello world.
at the beginning of <body>
tag.$ mkdir hugo-mod-hello
$ cd hugo-mod-hello
$ hugo mod init github.com/user/hugo-mod-hello
1[params.hugopress.modules.hello.attributes.document]
2[params.hugopress.modules.hello.hooks.head-end]
3[params.hugopress.modules.hello.hooks.body-begin]
We need to specify the attributes and hooks used by the module in config.toml
.
$ tree layouts/partials/hugopress/modules/hello
├── attributes
│ └── document.html
└── hooks
├── body-begin.html
└── head-end.html
The module files should be placed under the layouts/partials/hugopress/modules
folder.
The source code can be found at hello module files.
1[params.hugopress.modules.hello]
2disable = true
1[params.hugopress.modules.hello.attributes.document]
2cacheable = true
3
4[params.hugopress.modules.hello.hooks.body-begin]
5cacheable = true
Lower weight gets higher precedence.
1[params.hugopress.modules.hello.hooks.body-begin]
2weight = 1
Name | Description |
---|---|
{{ partial "hugopress/functions/has-modules" $hookName }} | Indicate if there are modules associate to the specified hook. |
{{ partial "hugopress/functions/exists" $moduleName }} | Indicate whether the module exists. |
{{ partial "hugopress/functions/is-disabled" $moduleName }} | Indicate whether the module was disabled, false if module doesn’t exist. |