Modules Cache

August 11, 2025 5 min read Docs

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.

Overview

Hugo downloads and caches external modules (like HBStack components) locally to improve build performance and enable offline development. These cached modules contain the actual source code, templates, assets, and configuration files that power your site.

Cache Location

Hugo stores modules in your user’s cache directory:

1# Linux/macOS
2~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/
3
4# Windows
5%LOCALAPPDATA%\hugo_cache\modules\filecache\modules\pkg\mod\

In my settings, the cache is located at:

1/home/ag-sayyed/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/

Cache Structure

The cache follows Go module conventions with this structure:

1github.com/hbstack/
2├── blog@v0.42.1/           # Blog module at version 0.42.1
3├── docs@v0.24.0/           # Documentation module at version 0.24.0
4├── gallery@v0.13.1/        # Gallery module at version 0.13.1
5├── base@v0.6.2/            # Base module at version 0.6.2
6├── header@v0.16.6/         # Header module at version 0.16.6
7└── [module-name@version]/  # Each module has its own versioned directory

Each module directory contains:

layouts/ - Hugo template files
assets/ - CSS, JS, and other assets
static/ - Static files
i18n/ - Internationalization files
go.mod - Module dependencies
hugo.toml - Module configuration

Note
The cache structure may vary slightly based on the module and its versioning. Some may contain additional directories like data.

Config command and Cache Exploration

Hugo provides a config command to understand the configuration of the site. It shows the current configuration, including parameters set in config.yaml or config.toml. It also displays the modules used in the site with other configuration details. It is useful for debugging and understanding how the site is set up but a very long output. Since we are interested in the modules cache, we can use the config command to see the cache settings in the site using pipe and grep commands.

1hugo config | grep - i cache
2# or to be more specific
3hugo config | grep - i cacheDir
4# once you know the cache directory, you can explore it further.
5ls -la /home/ag-sayyed/.cache/hugo_cache/
6ls -la /home/ag-sayyed/.cache/hugo_cache/modules/
7ls -la /home/ag-sayyed/.cache/hugo_cache/modules/filecache/
8ls- la /home/ag-sayyed/.cache/hugo_cache/modules/filecache/modules/
9ls -la /home/ag-sayyed/.cache/hugo_cache/modules/filecache/modules/pkg

Essential Commands for Cache Exploration

1. Finding All HBStack Modules

1# List all HBStack modules in cache
2ls -la /home/ag-sayyed/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/
3
4# Find modules with specific patterns
5find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -maxdepth 1 -name "*blog*"
6find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -maxdepth 1 -name "*docs*"

2. Exploring Module Contents

1# List contents of a specific module
2ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/
3
4# Check if module has layouts
5ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/layouts/
6
7# Check if module has assets
8ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/assets/

3. Finding Layout Templates

1# Find all layout directories across HBStack modules
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "layouts" -type d
3
4# Find specific template files
5find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "single.html"
6find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "list.html"
7find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "*.html" | grep -E "(blog|docs|gallery)"

4. Examining Template Content

1# View template content
2cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/layouts/blog/single.html
3
4# Search for specific content in templates
5grep -r "partial" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/layouts/

5. Finding Partials and Shortcodes

1# Find all partials
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -path "*/partials/*.html"
3
4# Find shortcodes
5find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -path "*/shortcodes/*.html"
6
7# List partials in a specific module
8ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/layouts/partials/

6. Module Configuration and Dependencies

1# Check module configuration
2cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/hugo.toml
3
4# Check Go module dependencies
5cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/go.mod
6
7# Find all hugo.toml configuration files
8find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "hugo.toml"

7. Asset and Static File Exploration

1# Find CSS and SCSS files
2find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "*.scss"
3find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "*.css"
4
5# Find JavaScript files
6find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -name "*.js"
7
8# Find static assets
9find ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ -path "*/static/*"

Advanced Search Techniques

1. Content-Based Searches

1# Search for specific functions or partials across all modules
2grep -r "hb/modules/blog" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/
3
4# Find templates that use specific Hugo functions
5grep -r "\.Paginate" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/
6
7# Search for parameter usage
8grep -r "\.Site\.Params\.hb" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/

2. Version Comparison

1# Compare different versions of the same module
2ls -la ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ | grep blog
3diff ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/layouts/blog/single.html \
4     ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.35.3/layouts/blog/single.html

3. Module Dependency Mapping

1# Find which modules depend on others
2grep -r "github.com/hbstack" ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/*/go.mod
3
4# Check module imports in a specific module
5cat ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/blog@v0.42.1/go.mod

Cache Management Commands

1. Cache Information

1# Check cache size
2du -sh ~/.cache/hugo_cache/
3
4# Count cached modules
5ls -1 ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ | wc -l
6
7# Show module versions
8ls -1 ~/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/hbstack/ | sort

2. Cache Maintenance

1# Clear Hugo module cache (use with caution)
2hugo mod clean
3
4# Force module download/update
5hugo mod get -u
6
7# Download specific module version
8hugo mod get github.com/hbstack/blog@v0.42.1

Vendor Directory

Hugo are Go modules, and they can be vendored for better performance. The above shows how to find the modules in the cache, using manual search commands. But you can also use the a hugo commands to see the vendor directory in your project.

1# List all modules in the vendor directory
2hugo mod vendor

The above command show you the _vendor directory in your project root, which contains all the modules used in your site. This is useful for offline development and for ensuring that your site has all the necessary dependencies bundled with it.

 1.
 2└── github.com
 3    ├── agsayyed
 4    ├── gohugoio
 5    ├── hbstack
 6    ├── henrygd
 7    ├── hugomods
 8    ├── KaTeX
 9    ├── tabler
10    ├── Templarian
11    └── twbs
12
13# The above shows the _vendor directories structure, which contains all the modules used in in your site from `github.com` domain.
14
15```bash
16.hbstack
17├── bigger-picture
18│   ├── assets
19│   └── layouts
20├── blockquote-alerts
21│   ├── assets
22│   ├── i18n
23│   └── layouts
24├── bootstrap
25│   └── assets
26├── breadcrumb
27│   ├── assets
28│   ├── i18n
29│   └── layouts
30├── bs-tooltip
31│   └── assets
32├── gallery
33│   ├── assets
34│   ├── i18n
35│   ├── layouts
36│   └── modules
37├── hb
38│   ├── assets
39│   └── layouts
40├── shortcodes
41│   ├── assets
42│   └── layouts
43└── syntax-highlighting
44    ├── assets
45    └── styles

The above shows the _vendor directory structure, which contains all the modules used in your site from hbstack domain.

FAQs

Advanced Search

Browse Courses