Directories

Right, let’s talk about where your system actually puts all its stuff. You’ve probably poked around in the root directory (/) and seen a bunch of these cryptic folders. They’re not there by accident (well, mostly). They follow a grand, ancient blueprint called the Filesystem Hierarchy Standard, or FHS. It’s the reason you can, generally, expect to find libraries in /lib and not, say, in /where_did_i_put_that. We’re going to crack open four of the most commonly misunderstood ones: /lib, /usr, /opt, and /srv.

Right, let’s talk about /dev. You’ve probably seen it, a directory full of what look like files with weird names like sda, ttyS0, and null. They are files, but they’re not files in the way you and I usually think about them. They’re not containers for data you wrote. They’re more like magical portals. Opening and writing to one of these files doesn’t hit a disk; it talks directly to a piece of hardware, or a software abstraction so fundamental the kernel provides it.

Right, let’s talk about two of the most useful and most misunderstood directories on your system: /proc and /sys. You’ve seen them, you’ve probably been told not to touch them, and you’ve maybe even peeked inside. They look like regular directories, but they’re not. They’re a live, dynamic, and utterly fascinating view into the kernel’s soul. Think of them as the kernel’s debug console and control panel, magically mapped into your filesystem because, well, it was the most clever way the designers could think of to let user-space programs interact with it.

Right, let’s talk about the two directories on your system that are designed to be forgotten: /tmp and /run. They’re the digital equivalent of a whiteboard—incredibly useful for scribbling down a thought, but you’d be horrified if that scribble became a permanent fixture on your wall. They hold data that only matters right now. The key difference between them is a question of ownership: is this temporary data for you, the user, or for the system and its services?

Right, let’s talk about /var. If / is the root of your system’s universe and /usr is the pristine, read-only library of software, then /var is the messy, bustling, constantly-changing workshop where the actual work gets done. The name stands for “variable,” and it’s where anything that grows, shrinks, or changes on its own accord lives. Think of it as the system’s scratch paper, its inbox, its ledger, and its diary, all rolled into one.

Right, let’s talk about where you live. No, not your physical house—your digital one. On a Linux system, your personal slice of the universe is /home/your_username. It’s your bedroom in the sprawling mansion of the operating system: you get to put posters on the walls, leave dirty socks on the floor, and generally arrange things as you see fit. The system and other users (mostly) have to knock before coming in.

Right, let’s talk about /etc. Forget the urban legend that it stands for “Et Cetera”—it doesn’t. It’s just the name. This is the directory where your system goes to get its marching orders. If your Linux machine were a person, /etc would be its personality, its habits, and all the little rules it lives by. This isn’t for your data or your programs; this is for the system’s configuration. And it’s a glorious, sometimes horrifying, mess of text files.

Right, let’s talk about the three bins in the room: /bin, /sbin, and /usr/bin. You’ve seen them. You’ve probably used them without a second thought. But why are there three places for what is essentially the same thing: executable programs? The answer is a delightful mix of historical baggage, practical necessity, and a few decisions that make you wonder if the designers were running on a serious caffeine deficit. It all boils down to one question: “What do you absolutely need to boot and repair a system when your /usr partition is sitting on a network drive that hasn’t mounted yet, or is corrupted beyond recognition?” This isn’t a theoretical question. I’ve been there, staring at a initramfs prompt, thanking my lucky stars that ls, mount, and fsck were still available. That’s the core of the split.

Right, let’s talk about /. No, not your website’s root directory. This is the real root. The one directory to rule them all. Forget C:\ from Windows; that’s just a drive letter. Here, / is the absolute, unequivocal starting point for every single file and directory on the system. It’s the cosmic singularity from which the entire universe of your OS expands. If a file’s path doesn’t start with a /, it’s relative to wherever you currently are. If it does, the system knows exactly where to go, no matter what.

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.