Alright, let’s get our hands dirty with the file that tells Hugo how to behave: the configuration file. You’ll find this bad boy at the root of your project, named hugo.toml, hugo.yaml, or hugo.json. The format is your call; I’m a TOML person because it strikes a nice balance between being human-readable and not needing to care about indentation like YAML. Hugo doesn’t play favorites; it’ll use whichever one it finds first, in that order.
Right, let’s talk about the public/ directory. This is where the magic happens, or more accurately, where the result of the magic is dumped. It’s the single most important directory in your project, and yet, you will almost never directly touch a file inside it. Intrigued? You should be. Think of your Hugo project as a kitchen. Your content/, layouts/, and static/ directories are your countertops, ingredients, and recipes. The public/ directory is the clean, polished plate of food you serve to your guests. You don’t prepare the food on the plate; you prepare it and then put it on the plate. This directory is that final, served plate. It contains the entire, fully rendered, static website. Every HTML file, every CSS file, every image that’s been processed, every JavaScript asset—all of it, perfectly arranged and ready to be uploaded to a web server.
Right, themes/. This directory is simultaneously the most exciting and most dangerous part of your Hugo project. It’s where you go to completely change the personality of your site without touching your precious content. Think of it like a theme park: you can have a fun, safe time on the well-maintained rides, or you can wander off into the backlot and get yelled at by a man in a stained jumpsuit for trying to hot-wire the spinning teacups.
Right, the static/ directory. This one is beautifully simple, which is why so many of you will get it wrong. I’m not here to judge; I’ve done it myself. Here’s the deal: anything you put in here gets copied exactly as-is directly into your final public/ folder when you run hugo. No processing. No minification. No finger-wagging from Hugo’s templating engine. It’s a straight, verbatim file copy. Think of it as the VIP backstage pass for your files. They bypass the whole bouncer-and-velvet-rope system (Hugo’s processing pipeline) and get dropped right into the middle of the party.
Alright, let’s get our hands dirty with layouts/. This is where Hugo stops being a simple content organizer and transforms into a proper static site generator. Think of this directory as your workshop, filled with blueprints (templates) that dictate how every single page on your site will be built. Without these, Hugo would just have a pile of lumber and nails (your content) with no idea how to assemble a house.
Right, the i18n/ directory. This is where we stop pretending everyone speaks the same language and start doing the actual, hard work of making your site accessible to a global audience. Don’t call it “translation files”; call them “string dictionaries.” It’s a more accurate term. You’re not just translating words; you’re mapping a key (like homepage.title) to a string of text in a specific language. Hugo uses this directory to pull the correct text based on the site’s current language configuration. It’s brilliantly simple in concept, but the devil, as always, is in the details.
Right, let’s talk about the data/ directory. This is Hugo’s secret weapon for when you need to manage structured information that isn’t a page. Think of it as your project’s personal database, but infinitely simpler and stored as text files. It’s where you put all the stuff that makes your site dynamic—product listings, team member bios, a curated list of your favorite terrible movies, you name it. The genius here is that you can access this data from any template, anywhere on your site. No more hard-coding the same list of links in twenty different pages. You define it once in data/ and then iterate over it. It’s the DRY (Don’t Repeat Yourself) principle, and Hugo enforces it with the subtlety of a sledgehammer, which I appreciate.
Alright, let’s talk about the content/ directory. This is the big one. This is where your actual words live. If your Hugo site were a restaurant, the layouts/ folder would be the kitchen and waitstaff, the themes/ folder would be the interior design, but content/ is the food. And nobody comes back for the pretty chairs if the food is terrible. Hugo’s content management is brilliantly simple at its core: the structure of your content/ directory dictates the structure of your published website. It’s a 1:1 mapping. A file at content/posts/my-awesome-post.md will, by default, be rendered at yoursite.com/posts/my-awesome-post/. This is Hugo’s “convention over configuration” philosophy working in your favor. Stop fighting it and embrace it. It will save you countless hours.
Right, let’s talk about the assets/ directory. This is where you put the raw materials—the stuff that isn’t ready for the web just yet. Think of it as your workshop, not the showroom. These are the files you want Hugo, specifically its Hugo Pipes feature, to get its hands dirty with: your un-minified CSS, your un-bundled JavaScript, your un-optimized images, your SASS/SCSS files. The magic, and the entire reason this directory exists, is that only files in the assets/ directory (and a few other designated folders) are available to Hugo’s template functions like resources.Get. You can’t just reach into some random folder from your template; Hugo needs to know where to look for these source files. This is a good thing. It keeps things organized and prevents you from accidentally processing your taxes_2022.xlsx file as a Sass stylesheet, which would probably result in a very depressing color scheme.
Right, let’s talk about archetypes/. This directory is one of those Hugo features that seems almost trivial until you use it correctly, at which point you wonder how you ever lived without it. It’s the antidote to the soul-crushing tedium of manually creating the same front matter for every new blog post, product page, or whatever content type you have. Think of an archetype as a template for new content. It’s a blueprint. When you run hugo new posts/my-great-post.md, Hugo doesn’t just create a blank file. It looks in archetypes/ for a file named posts.md (or the default default.md) and uses it to pre-populate that new file with front matter. This is how you avoid forgetting to set that draft: true flag for new posts or manually typing out the same taxonomy every single time.