Dependencies

Alright, let’s talk about Workspace Mode. You know that special kind of hell where you’re trying to develop a local Hugo module—your beautiful, custom theme or components module—while simultaneously testing its integration in your main site? You’re constantly cd-ing back and forth, running hugo mod tidy in both directories, and committing half-baked changes just to push a version tag so your main project can pull it in via go.mod. It’s a workflow designed by someone who has never actually had to use this workflow. It’s tedious, error-prone, and frankly, a bit insulting to your intelligence.

Right, so you’ve decided to build a Hugo theme component. Excellent choice. This is how we stop copying and pasting the same header.html partial across seventeen different projects and finally get paid for our good taste. A theme component is just a Hugo Module that lives in its own repository and gets pulled into your main project as a dependency. It’s like giving your best layouts their own apartment instead of letting them crash on your couch indefinitely.

Right, let’s talk about hugo mod tidy and vendor. These two commands are your best friends for keeping your Hugo project’s dependencies from turning into a digital hoarder’s paradise. They’re the dynamic duo of dependency management, and you’re about to become the commissioner. First, hugo mod tidy. This is your cleanup crew. You know how go mod tidy prunes the unused crud from your go.mod and go.sum? This is the exact same concept, just wearing a Hugo-themed cape. When you’re experimenting with modules—adding a theme here, trying a cool shortcode module there—your go.mod file can accumulate entries for things you’re no longer using. This isn’t just messy; it can cause conflicts or pull in unnecessary code. Running hugo mod tidy sweeps through your project, looks at what you’re actually importing in your config, and then ruthlessly evicts any module requirements that aren’t needed. It’s the Marie Kondo of your Hugo project. If it doesn’t spark joy (or, more accurately, if it doesn’t resolve a config directive), it’s gone.

Right, so you’ve got your modules set up. They’re fetching, your site builds. Wonderful. Now comes the part where you make sure this beautiful house of cards doesn’t collapse in six months when some dependency decides to release a wildly breaking change. Because they will. Trust me. Hugo modules use Go’s toolchain, specifically go mod, for dependency management, which is both a blessing and a curse. It’s incredibly powerful, but it has its own… let’s call them idiosyncrasies. We’re going to wrestle it into submission.

Right, so you’ve got a Hugo module imported. Great. It’s sitting there in your go.mod file, a neat little line of code promising functionality. But Hugo, in its infinite wisdom, doesn’t just blindly copy the entire contents of that remote repository into your themes or layouts directory. That would be chaos. Instead, it gives you a surgical tool: the mount. This is how you tell Hugo, “See that specific folder inside the module? Yeah, pretend it’s right here in my project, and use it exactly like my local files.” It’s a symlink on steroids, managed by Go.

Right, let’s talk about module.imports. This is where you stop pretending your Hugo site is a lone wolf and start admitting it needs friends. Or, more accurately, libraries. This configuration block is your explicit declaration of dependency, your way of telling Hugo, “Hey, go get this other code from over there so we can use it here.” Forget the old theme setting; that was a blunt instrument. module.imports is a scalpel. It’s how you pull in other Hugo Modules—which could be full-blown themes, just a few templates, or a single archetype file—with surgical precision. The magic behind this is Go Modules, which Hugo leans on. This means you get proper versioning, and you don’t have to nervously copy and paste layouts/ directories anymore like some digital hoarder.

Right, let’s get this party started. You’ve decided to use Hugo Modules, which means you’ve graduated past just dropping themes into a themes folder. Good for you. This is the modern, sane way to manage dependencies in Hugo, and it’s all built on top of Go’s own dependency management system, go mod. Don’t worry if you don’t know Go; you’re about to learn just enough of its tooling to be dangerous in the best way possible.