Theme-Development

Right, so you’ve built this beautiful, clever Hugo theme. It’s a masterpiece of semantic HTML and clever partials. You, my friend, are an artist. But art locked in a closet is just hoarding. It’s time to unleash your creation upon the world via the Hugo Themes Gallery. This isn’t just a matter of pushing to GitHub and calling it a day. Hugo has a… let’s call it a particular set of requirements. They’re not difficult, but they are non-negotiable, and missing one will leave your theme languishing in “draft” status forever.

Right, so you’ve built a theme. It looks sharp. But here’s the problem: it’s a dictatorship, not a democracy. You’ve hard-coded the accent color to that specific shade of electric teal you’re so fond of, and the site title is set in stone. What if your user wants… gasp… maroon? We’re not barbarians. We need to hand over the reins, but in a controlled, sensible way. That’s where Hugo’s Params come in. Think of them as the control panel for your theme, letting the user tweak things without ever having to touch a line of Go template code.

Right, so you want a dark mode toggle. Not just a little switch that winks an eye and hopes for the best, but a proper, persistent, system-respecting one. We’ve all seen the janky versions—the ones that flashbang you at 2 AM or forget your preference the moment you reload. We’re not building that. We’re building the one that does it right, because frankly, the user experience here is embarrassingly easy to screw up. Let’s get it right on the first try.

Right, so you’ve decided to build a Hugo theme. Good for you. You’ve got your HTML templated, your CSS is piping hot, and now you need some actual, functioning JavaScript. You could just slap a <script src="main.js"> in your head and call it a day, but then you’d be serving a massive, un-minified, ES6+ mess to every browser, including a Nokia phone running Opera Mini. We’re better than that. Enter Hugo Pipes and esbuild. This is where Hugo stops being a simple static site generator and starts feeling like a full-fledged build tool. The beauty of it is that you don’t need a separate package.json, node_modules, or a sprawling Webpack configuration that requires a blood sacrifice to maintain. Hugo handles it all internally, and it’s brilliantly fast.

Right, let’s talk strategy. You’re about to build a theme, which means you’re making decisions that will haunt you—or bless you—for the entire project. The way you structure your CSS isn’t just about writing styles; it’s about writing maintainable styles that won’t make you want to set your computer on fire in six months. We have three main players here: the purity of Vanilla CSS, the utility-first speed of Tailwind, and the programmatic power of SCSS. The good news is, you don’t have to choose just one. The better news is, if you mix them wrong, you’ll create a monster. Let’s get it right.

Right. You’ve decided to build a theme from scratch. Good for you. This is where you stop being a tourist and start being a citizen. You’ll get your hands dirty, you’ll make mistakes, and you’ll learn more in the next ten minutes than you would from installing fifty pre-made themes. The base template is the bedrock. It’s the single most important file in your theme. Get this right, and everything else slots into place. Get it wrong, and you’ll be chasing weird bugs for weeks.

Right, let’s talk about the theme.toml file. This is your theme’s handshake, its business card, and its legally binding contract with Hugo, all rolled into one. Get this wrong, and Hugo will either throw a fit or, worse, build your theme with a whimper instead of a bang. It’s a TOML file because, well, the Hugo team made a choice. I don’t question the cosmic reasoning; I just write the config.

Right, let’s get our hands dirty. You’re building a theme from scratch, which means you’re about to become intimately familiar with a very specific directory structure. This isn’t arbitrary bureaucracy; it’s Hugo’s contract with you. You put things in the right place, and Hugo, being a deeply opinionated but brilliant curmudgeon, knows exactly what to do with them. Break the contract, and things just… stop working. Let’s look at the four key directories you’ll be living in.