Right, you’ve got Hugo installed. Don’t get cocky. That was the easy part. Now we get to the command that feels like a magic spell but is really just a very organized, slightly opinionated file clerk: hugo new site.

Think of this command as your site’s ground zero. It doesn’t just make a folder; it builds the entire scaffold, the skeleton, the filing system that Hugo expects to find every time it goes to build your site. Run it, and for the love of all that is holy, give your project a sensible name. Not my-website. Not test-site-7. You’re better than that.

hugo new site my-brilliant-blog

Hit enter. If you did it right, you’ll see a friendly message like “Congratulations! Your new Hugo site is created in /path/to/my-brilliant-blog.” Let’s cd into that directory and see what our new digital real estate looks like.

cd my-brilliant-blog
ls -la
# Or 'dir' if you're on Windows, but we both know you saw 'ls' and knew what it meant.

The Project Structure: A Tour of the Empty Manor

You’re now looking at the absolute minimum viable structure for a Hugo site. It’s a bit like walking into a perfectly built, fully wired new house… with no furniture. Here’s what you’ve got:

.
├── archetypes/
├── content/
├── data/
├── layouts/
├── static/
├── themes/
└── config.toml

Let’s break down what these empty rooms are for, because Hugo will be very particular about what goes where.

  • content/: This is the big one. This is where 95% of your actual writing lives. Every post, every page, every thing you want to appear on your site goes in here, organized into subdirectories. It’s the heart of the operation.
  • layouts/: This is your custom override department. If you don’t like how a theme renders a particular page, you don’t change the theme’s files (that’s a maintenance nightmare). You copy the relevant file from the theme into this directory and hack it to your liking. Hugo is smart enough to use your version first.
  • static/: This is for everything that gets served exactly as-is. Images, PDFs, JavaScript files, CSS that isn’t part of a theme. Hugo won’t process these files; it just copies them directly into the final public/ site structure. If you have a favicon.ico, this is its home.
  • themes/: You’ll install your theme here. We’ll get to that next. For now, it’s an empty directory, taunting you.
  • archetypes/: This is a productivity hack. Archetypes are templates for new content files. When you run hugo new posts/my-first-post.md, Hugo checks here for a posts.md archetype to pre-populate the front matter. If it doesn’t find one, it uses the default. We can ignore this for now.
  • data/: For when you need to use external data files (JSON, YAML, TOML) that aren’t your content. Think a list of team members or projects. Fancy, but not for day one.
  • config.toml: The brains of the operation. The settings. The rules. This is a TOML file (because that’s what the Hugo devs preferred at the time, though it now supports YAML and JSON too) that holds all your site-wide configuration. This is where you’ll set your title, configure your theme, and tell Hugo how to behave.

The Config File: Your First Point of Order

Open up config.toml in your text editor. It’s… sparse.

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

This is the absolute bare minimum. The baseURL is crucial—it’s the root of your final website. For now, http://example.org/ is fine for local development, but when you deploy, you’ll must change this to your actual domain, or your CSS and links will all break spectacularly. It’s the most common “my site looks broken on the server” pitfall, and I’ve done it more times than I care to admit.

We’ll be adding a lot more to this file soon, but for now, just acknowledge its existence. It’s the contract between you and the Hugo engine.