This guide explains how the HBStack framework manages modules cache, including the purpose of the cache, how to view cached templates, and the implications of using cached modules.
This guide explains how the HBStack framework manages modules cache, including the purpose of the cache, how to view cached templates, and the implications of using cached modules.
When working with HBStack, you may need to explore the cached modules to understand how they work or to customize them. The cache is stored in your local file system, and you can search through it using various commands discussed earlier.
When you want to customize a layout, first examine the original:
1# Find the template you want to customize
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "single.html" | grep blog
3
4# Examine the template
5cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/layouts/blog/single.html
6
7# Check what partials it uses
8grep "partial" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/layouts/blog/single.html
1# See what layouts a module provides
2ls ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/docs@v0.24.0/layouts/
3
4# Check module's parameter configuration
5cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/docs@v0.24.0/hugo.toml
1# Search for a specific shortcode across all modules
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -path "*/shortcodes/*.html" -exec basename {} \; | sort | uniq
3
4# Find which module provides a specific partial
5find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -path "*/partials/hb/modules/blog/*" -name "*.html"
Let’s walk through a real example of how to identify which HBStack module controls the navigation bar/header functionality.
1# Search for header modules
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -maxdepth 1 -name "*header*"
3
4# Results show:
5# /home/ag-sayyed/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6
6# /home/ag-sayyed/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.15.0
7# ... (multiple versions)
1# Check what's in the latest header module
2ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/
3
4# Look for layouts directory
5ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/layouts/
1# Find all header template files
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/layouts/ -name "*.html"
3
4# Key files discovered:
5# /layouts/partials/hb/modules/header/index.html # Main header template
6# /layouts/partials/hb/modules/header/menus.html # Navigation menus
7# /layouts/partials/hb/modules/header/brand.html # Logo/brand area
8# /layouts/partials/hb/modules/header/menu.html # Individual menu items
9# /layouts/partials/hb/modules/header/submenu.html # Dropdown submenus
1# View the main header template
2cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/layouts/partials/hb/modules/header/index.html
Key Findings:
navbar-expand-{{ $breakpoint }}hb-header-panel, hb-header-nav-begin, etc.$.Site.Params.hb.header1# Find header submodules
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "*header*" -type d | grep "modules"
3
4# Submodules found:
5# header/modules/banner@v0.7.2 # Header banners
6# header/modules/theme-toggle@v0.5.2 # Dark/light theme toggle
7# header/modules/socials@v0.2.2 # Social media links
8# header/modules/language-picker@v0.2.0 # Language selection
9# header/modules/search@v0.1.38 # Search functionality
1# Search for hook usage in header templates
2grep -r "render-hooks" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/layouts/
3
4# Hook points discovered:
5# hb-header-begin # Start of header
6# hb-header-nav-before # Before navigation container
7# hb-header-nav-begin # Start of navigation content
8# hb-header-togglers-begin # Before toggle buttons
9# hb-header-togglers-end # After toggle buttons
10# hb-header-panel # Header panel area (right side)
11# hb-header-nav-after # After navigation container
12# hb-header-end # End of header
1# View header module configuration
2cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/hugo.toml
3
4# Search for parameter usage
5grep -r "\.Site\.Params\.hb\.header" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/
Based on this analysis, here’s how to extend header functionality:
hbstack/header@v0.16.6/layouts/partials/hb/modules/header/index.html in your siteparams.hb.header in your site config/config/_default/menus.en.yaml/layouts/partials/hb/modules/header/menus.htmlheader/modules/search for search functionalityheader/modules/theme-toggle for dark/light modeheader/modules/socials for social media linksheader/modules/language-picker for i18n1# Create custom header hooks in your layouts
2/layouts/partials/hugopress/modules/hb-header-panel/my-custom-widget.html
1# Find header SCSS files
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/assets/ -name "*.scss"
1# Header modules
2alias find-header="find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name '*header*'"
3
4# Navigation templates
5alias header-templates="find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/layouts/ -name '*.html'"
6
7# Header configuration
8alias header-config="cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/hugo.toml"
9
10# Header hooks
11alias header-hooks="grep -r 'render-hooks' ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/header@v0.16.6/layouts/"
This systematic approach works for any HBStack module - just replace “header” with your target functionality (footer, blog, docs, etc.)!
Read-Only: Cached modules are read-only. Never edit files directly in the cache.
Version Specific: Each module version is cached separately. Always check the version you’re examining matches your go.mod file.
Cache Invalidation: Hugo automatically manages cache updates when you run hugo mod get -u.
Backup: The cache can be safely deleted and will be rebuilt on next hugo command.
Development Workflow: Use cache exploration for understanding, then create overrides in your local /layouts/ directory.
This cache system allows you to understand exactly how HBStack modules work and provides the foundation for effective customization and debugging!
Content.