Why is my theme module not working? Should I vendor it?

Stradichenko · June 4, 2025, 12:36pm

I want to use my own theme on my personal blog (a different repo). But when trying to import theme as a module, the site renders but only with boilerplate elements, not with custom theme…

I have the following doubts:

What am I doing wrong?
What rule of thumb should I follow to know if my blog needs to vendor my theme?

These are my installation steps (WIP)

# 0. Create boilerplate files for your site, replace placeholder title (in case of testing locally anything like <example.com/my-blog> works fine)
hugo new site <your-site>
cd <your-site>

# 1.2 To initialize say your blog as a module using Github for example; by creating a go.mod file
hugo mod init github.com/<your-username>/<your-blog>

# 2. add theme module to site
cat <<EOF >> hugo.toml

[module]
  [[module.imports]]
    path = 'github.com/stradichenko/PKB-theme'
EOF

# 2.1 for better file organization
mkdir -p config/_default/ config/development && mv ./hugo.toml config/_default/
curl -L -o config/development/hugo.toml https://github.com/stradichenko/PKB-theme/raw/main/config/development/hugo.toml

# 3. Download the theme as a module
hugo mod get

# removes_unused Dependencies not referenced in config, updates checksum, Verifies module integrity. optimizes module dependency tree
hugo mod tidy

# Verify what changed
git diff go.mod go.sum

# vendoring
hugo mod vendor

# 4. This will copy params for the user to customize
curl -L -o config/_default/params.toml https://github.com/stradichenko/PKB-theme/raw/main/config/_default/params.toml

# just to make sure the the theme was imported 
hugo mod graph
# > github.com/<your-username>/<your-blog> github.com/stradichenko/PKB-theme@v0.0.1

# test blog with drafts
rm -rf .cache/hugo/ resources/ public/ tmp/ .hugo_build.lock && hugo server --source . --noHTTPCache --renderToMemory --disableFastRender --ignoreCache --gc --logLevel debug -D -e development

I have tried vendoring my theme to my blog, but the vendored files are just boilerplate files, not the ones from my theme:

_vendor/

tree _vendor
_vendor
├── github.com
│   └── stradichenko
│       └── PKB-theme
│           ├── archetypes
│           │   └── default.md
│           ├── assets
│           │   ├── css
│           │   │   └── main.css
│           │   └── js
│           │       └── main.js
│           ├── content
│           │   ├── _index.md
│           │   └── posts
│           │       ├── _index.md
│           │       ├── post-1.md
│           │       ├── post-2.md
│           │       └── post-3
│           │           ├── bryce-canyon.jpg
│           │           └── index.md
│           ├── hugo.toml
│           ├── layouts
│           │   ├── _default
│           │   │   ├── baseof.html
│           │   │   ├── home.html
│           │   │   ├── list.html
│           │   │   └── single.html
│           │   └── partials
│           │       ├── footer.html
│           │       ├── head
│           │       │   ├── css.html
│           │       │   └── js.html
│           │       ├── header.html
│           │       ├── head.html
│           │       ├── menu.html
│           │       └── terms.html
│           ├── static
│           │   └── favicon.ico
│           └── theme.toml
└── modules.txt

16 directories, 24 files

This is my blog’s

config/development/hugo.toml:

# Development-specific configuration
baseURL = "http://localhost:1313/"
title = 'development'


[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        enableDefault = true
      [markup.goldmark.renderHooks.link]
        enableDefault = true
    [markup.goldmark.renderer]
      unsafe = true  # This allows raw HTML in markdown files

[module]
  [[module.imports]]
    path = "github.com/stradichenko/PKB-theme"
    # version = "v1.0.0"  # optional pin once you have tags

    [[module.imports.mounts]]
      source = "static" # inside the theme repo
      target = "static" # inject it into my site’s    

    [[module.imports.mounts]]
      source = "assets"
      target = "assets"

    [[module.imports.mounts]]
      source = "content"
      target = "content"

    [[module.imports.mounts]]
      source = "layouts"
      target = "layouts"

    [[module.imports.mounts]]
      source = "archetypes"
      target = "archetypes"

My blog’s go.mod:

module github.com/stradichenko/krotanote

go 1.23.9

require github.com/stradichenko/PKB-theme v0.0.1 // indirect

My blog’s go.sum:

github.com/stradichenko/PKB-theme v0.0.1 h1:6MYR7C2yamfGXTyJtrST4zWjV2XKD/2j/YPOhTwXoVE=
github.com/stradichenko/PKB-theme v0.0.1/go.mod h1:O+FAjAgk9Zwweu+69JDnAP0mftf7z2Y1eeUg+wt//o8=

Additional information:

The theme has been turned to a module and have the necessary files (I think), this is it.
The theme has the necessary tag:

pwd
~/USER/projects/PKB-theme
git tag -l
v0.0.1

bep · June 4, 2025, 1:17pm

You could start by telling us how it fails? Do you get an error message?

Stradichenko · June 4, 2025, 1:32pm

I wasn’t clear enough describing the issue. What I meant to say is that it fails to load the theme; the site renders but nothing gets imported as a module despite being described in the hugo.toml, the go.sum, the go.mod:

hugo server
hugo: collected modules in 935 ms
Watching for changes in ~/projects/krotanote/{archetypes,assets,content,data,i18n,layouts,static}
Watching for config changes in ~/projects/krotanote/config/_default, ~/projects/krotanote/config/development, ~/projects/krotanote/go.mod
Start building sites … 
hugo v0.126.2+extended linux/amd64 BuildDate=2024-07-18T00:00:00+00:00 VendorInfo=Fedora:0.126.2-3.fc41


                   | EN  
-------------------+-----
  Pages            | 18  
  Paginator pages  |  0  
  Non-page files   |  1  
  Static files     |  1  
  Processed images |  0  
  Aliases          |  0  
  Cleaned          |  0  

Built in 75 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

irkode · June 4, 2025, 2:15pm

looks like v0.0.1 has been tagged on March 17…maybe that’s what you get

Stradichenko · June 4, 2025, 2:42pm

Genius! That solved the issue:

The steps were:

Firstly, updated the tag of the theme:

# Force update tag to current commit
git tag -f v0.0.2

# Push updated tag
git push origin v0.0.2 --force

Then:

hugo mod get
hugo mod tidy
git diff go.mod go.sum
hugo mod vendor
hugo server --source . --noHTTPCache --renderToMemory --disableFastRender --ignoreCache --gc --logLevel debug -D -e development

In this case, I vendored, but I don’t understand when I should vendor or not; I just know it gets a local copy, but it feels bloated and less elegant.

I tried the following without _vendor/ folder and still worked; so… what’s the deal? haha:

hugo mod get
hugo mod tidy
git diff go.mod go.sum
hugo server --source . --noHTTPCache --renderToMemory --disableFastRender --ignoreCache --gc --logLevel debug -D -e development

irkode · June 4, 2025, 3:23pm

regarding vendoring: see Use Hugo Modules

for me the main things are:

committing the vendor folder will enable offlineand and reliable build.
enable to check code in the module without need to
- dig into the cache
  or
- need to clone
  for example clmpare last working theme with a pulled update

system · June 6, 2025, 3:24pm

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.

Topic		Replies	Views
Are Hugo modules the suggested way to provide and receive themes support	10	1792	August 6, 2019
My Hugo module does not work support modules	3	319	December 15, 2023
Tailoring (!?) themes when using Hugo modules Using Themes modules	5	198	March 24, 2024
Importing "theme" via modules results in building empty site support	3	270	January 24, 2024
How to use the theme at https://github.com/gohugoio/gohugoioTheme in my own site?	4	858	October 7, 2020

Why is my theme module not working? Should I vendor it?

Related topics