This guide explains how to override templates in Hugo modules, allowing for greater customization and flexibility in your site's design.
Using Hbstack modules is an easy option to use the functionality of existing templates while customizing them for your needs. By following a few simple steps, you can override any template in a module and provide your own implementation.
To override a template, you first need to identify the template file you want to change. This could be a layout file, a partial, or a shortcode. Once you’ve found the template you want to override, take note of its location within the module’s directory structure.
Once you’ve identified the template you want to override, the next step is to decide what changes you want to make. This could involve modifying the layout, changing the markup, or adding new functionality. Consider the following questions:
By answering these questions, you can create a clear plan for your template override.
A blog module is used as an example. It provides a set of templates for displaying blog posts, including lists, single post views, and archives. It is located at - path: github.com/hbstack/blog.
First thing to find out is the requirements of this module or its dependencies. And what does it offer. Here is the module.toml.
1[[module.imports]]
2path = "github.com/hbstack/base"
3
4[[module.imports]]
5path = "github.com/hbstack/carousel"
6
7[[module.imports]]
8path = "github.com/hbstack/pagination"
9
10[[module.imports]]
11path = "github.com/hbstack/socials"
12
13[[module.imports]]
14path = "github.com/hugomods/gravatar"
15
16[[module.imports]]
17path = "github.com/hugomods/icons/vendors/bootstrap"
18
19[[module.imports]]
20path = "github.com/hugomods/images"
21
22[[module.imports]]
23path = "github.com/hugomods/masonry-js"
24
25[params.hb.terms]
26paginate = 12
27profile = true
28profile_metrics = true
29list_style = "" # available options: minimalist, cascade.
30
31[params.hb.blog]
32list_style = "" # available options: minimalist, cascade.
33list_pinned_posts = 1
34full_width = false
35paginate = 12
36post_date_format = ':date_long'
37post_thumbnail = true
38post_thumbnail_height = "160px"
39post_thumbnail_placeholder = ""
40post_thumbnail_default = "images/thumbnail.png"
41post_thumbnail_position = "top"
42post_thumbnail_resize_height = 360
43list_cols_md = 2
44list_cols_lg = 3 # won't work when sidebar was enabled.
45
46[params.hb.blog.archives]
47paginate = 30
48
49[params.hb.blog.home]
50pinned_posts_position = ""
51# taxonomies_style = 'toggle'
52
53[params.hb.blog.sidebar]
54position = "start"
55width = 0.35
56max_width = "320px"
57sticky = true
58
59[params.hb.blog.toc]
60position = "end" # start, end or content.
61
62[params.hugopress.modules.hb-blog.hooks.head-begin]
63cacheable = true
64cache_param_key = "external_url"
we see that the blog module has several dependencies, including base, carousel, pagination, socials, gravatar, bootstrap icons, images, and masonry-js. Additionally, it has various parameters for customizing the blog’s appearance and behavior, such as pagination settings, post thumbnail options, and sidebar positioning.
Yet it does not provide the structure of how module is organized or how to extend it. Understanding the module’s structure is crucial for effectively overriding templates and making customizations.
To effectively override templates in the
Hbstackmodule, you need to understand its directory structure and how templates are organized. It has been discussed in creating a module.
To find the module in your Hugo project, you can look in the Hugo modules cache directory. This is typically located at ~/.cache/hugo/modules/pkg/mod/ on Unix-based systems or %USERPROFILE%\.hugo\modules\pkg\mod\ on Windows. The exact place on this computer is shown below
1find /home/ag-sayyed/.cache/hugo_cache/modules/ -type d -name "blog"
2ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/
If you click this moduule it will be opened into the editor or you can open it in any editor.
1tree
2.
3├── assets
4│ └── hb
5│ └── modules
6│ └── blog
7│ └── scss
8│ ├── archives
9│ │ └── index.scss
10│ ├── _authors.scss
11│ ├── home
12│ │ ├── _carousel.scss
13│ │ ├── index.scss
14│ │ └── _taxonomies.scss
15│ ├── index.scss
16│ ├── post
17│ │ ├── _card.scss
18│ │ ├── _content.scss
19│ │ ├── _home.scss
20│ │ ├── index.scss
21│ │ ├── _intro.scss
22│ │ ├── _main.scss
23│ │ ├── _meta.scss
24│ │ ├── _summary.scss
25│ │ ├── _taxonomy.scss
26│ │ ├── _title.scss
27│ │ └── _toc.scss
28│ ├── _reboot.scss
29│ ├── _sidebar.scss
30│ ├── _terms.scss
31│ └── variables.tmpl.scss
32├── CHANGELOG.md
33├── CODE_OF_CONDUCT.md
34├── go.mod
35├── go.sum
36├── hugo.toml
37├── i18n
38│ ├── de.toml
39│ ├── en.toml
40│ ├── es.toml
41│ ├── fr.toml
42│ ├── ko.toml
43│ ├── ms.toml
44│ ├── pt-br.toml
45│ ├── pt.toml
46│ ├── ru.toml
47│ ├── vi.toml
48│ ├── zh-hans.toml
49│ └── zh-hant.toml
50├── layouts
51│ ├── archives
52│ │ └── list.html
53│ ├── authors
54│ │ └── terms.html
55│ ├── blog
56│ │ ├── list.html
57│ │ └── single.html
58│ ├── _default
59│ │ ├── blog.html
60│ │ ├── index.html
61│ │ ├── list.html
62│ │ ├── rss.xml
63│ │ ├── single.html
64│ │ ├── term.html
65│ │ └── terms.html
66│ ├── partials
67│ │ ├── hb
68│ │ │ └── modules
69│ │ │ └── blog
70│ │ │ ├── archives
71│ │ │ │ ├── list.html
72│ │ │ │ └── posts.html
73│ │ │ ├── author
74│ │ │ │ └── image.html
75│ │ │ ├── functions
76│ │ │ │ ├── filter-taxonomies.html
77│ │ │ │ ├── has-sidebar.html
78│ │ │ │ └── list-cols.html
79│ │ │ ├── helpers
80│ │ │ │ └── pinned-icon.html
81│ │ │ ├── home
82│ │ │ │ └── taxonomies.html
83│ │ │ ├── index.html
84│ │ │ ├── list.html
85│ │ │ ├── post
86│ │ │ │ ├── card.html
87│ │ │ │ ├── card-img.html
88│ │ │ │ ├── comments.html
89│ │ │ │ ├── meta
90│ │ │ │ │ ├── authors.html
91│ │ │ │ │ ├── date.html
92│ │ │ │ │ ├── first-section.html
93│ │ │ │ │ ├── reading-time.html
94│ │ │ │ │ └── taxonomies.html
95│ │ │ │ ├── pagination.html
96│ │ │ │ ├── summary.html
97│ │ │ │ └── toc.html
98│ │ │ ├── posts.html
99│ │ │ ├── posts-minimalist.html
100│ │ │ ├── sections.html
101│ │ │ ├── sidebar.html
102│ │ │ ├── single.html
103│ │ │ ├── taxonomies
104│ │ │ │ ├── default.html
105│ │ │ │ └── toggle.html
106│ │ │ ├── term
107│ │ │ │ ├── metrics.html
108│ │ │ │ ├── profile.html
109│ │ │ │ └── socials.html
110│ │ │ └── title.html
111│ │ └── hugopress
112│ │ └── modules
113│ │ └── hb-blog
114│ │ └── hooks
115│ │ └── head-begin.html
116│ └── shortcodes
117│ └── hb
118│ └── blog
119│ └── taxonomies.html
120├── LICENSE
121├── package.json
122├── package-lock.json
123├── README.md
124├── release-please-config.json
125├── renovate.json
126├── tsconfig.eslint.json
127└── update.sh
In your hugo repo where a blog module has been imported you need to override the template. If Hugo finds the template in your layout directory, it will use this one otherwise it will use the one you have imported. This is it and you have modified the existing template of any module. Similary, in order to change the style you need to over ride the same correspounding styles. The styles always go in assets directory so if we have decided to override card.html, we need to create a new file in assets/hb/modules/custom/scss/card.scss with the same name and add our custom styles there.
Note
The word custom means that it is the custom implementation of an existing module, which is present in a
hb/moduledirectory. It is to understand that you would have another directory in your assets folder asassets/custom, this is where your created assets goes and resides.