Right, let’s talk about the brainstem of your Hugo site: the hugo.toml file (or hugo.yaml or hugo.json—I don’t judge your life choices, but I’ll be using TOML because it’s the default and frankly, it’s fine). This is where you tell Hugo the absolute essentials it needs to not trip over its own feet and fall flat on its face when you run hugo. We’re going to focus on the big four top-level keys you absolutely must get right from the start.

Think of these as the “Hello, World!” of Hugo config, but with more long-term consequences. Get these wrong, and your site will either be a ghost town nobody can find or it’ll scream at you in the wrong language.

The Non-Negotiable: baseURL

This isn’t just a suggestion; it’s the single most important setting in your entire config. Get this wrong, and you’ll be plunged into a world of pain where every single one of your relative links is broken. Hugo uses this value as the absolute root of your published website. It’s the DNA for every <link>, every <script>, every href it generates.

Why is it such a big deal? Because Hugo pre-renders everything. It needs to know the site’s ultimate, public-facing address at build time to correctly resolve all those rel="canonical" tags and asset paths. If you set it to http://localhost:1313, your production site will try to load all its CSS from your local machine. Don’t do that. The internet doesn’t have access to your laptop. Probably for the best.

# Good: This is what your production site will live at.
baseURL = 'https://my-awesome-blog.netlify.app'

# Bad: This is a one-way ticket to Broken Link City.
# baseURL = 'https://localhost:1313'

The best practice? You should almost never hardcode this value directly. We’ll use environments to handle this later, because you are absolutely going to forget to change it back before deploying and you will yell at your screen. I know I have.

Your Site’s Name Tag: title

This one is straightforward, but its reach is long. This sets the site’s… well, title. It’s used in the default page titles (as in <title>My Site Title | About Me</title>), it’s likely used in your theme’s header, footer, and metadata. It’s the name of your digital baby.

title = "My Incredibly Witty Tech Blog"

There’s no magic or gotchas here. Just make it accurate. If you change it later, remember to run a full rebuild, as this value can be cached in surprising places.

Speaking Your Language: languageCode

This setting does two subtly different things, and most people only think of the first one.

  1. It sets the default language for your site’s HTML lang attribute (e.g., <html lang="en-us">). This is good for accessibility and SEO. It tells screen readers and search engines what linguistic rules to use.
  2. It sets the locale for things like date formatting. This is the part that trips people up. If your languageCode is en-us, your dates will format as MM/DD/YYYY. If it’s en-gb, you’ll get DD/MM/YYYY. If you set this to fr-fr and your theme supports it, your “Posted on” date might suddenly become publié le 05 juillet.
# American English, dates as MM/DD/YYYY
languageCode = 'en-us'

# British English, dates as DD/MM/YYYY
languageCode = 'en-gb'

# French, because vous êtes très sophistiqué
languageCode = 'fr-fr'

This is a default. If you’re building a multi-lingual site, this is the fallback. For a single-language site, this is your everything.

Telling Hugo What to Wear: theme

This is the key where you point Hugo to the theme you’ve chosen. It expects the name of the directory your theme lives in, inside the themes/ folder. You cloned it from GitHub, you didn’t just forget to move it, right? …Right?

The beauty (and occasional frustration) of Hugo themes is that they are directories, not intricate configurations. Setting this key tells Hugo “hey, when I don’t have a specific file or template in my own site structure, go look in this folder over here.”

theme = "anatole" # or "hugo-coder" or "papermod"

A common pitfall? Typos. If you set theme = "anotole", Hugo will silently fail. It won’t throw a big error; it will just proceed as if you have no theme, rendering a bland, unstyled mess and leaving you to wonder if you’ve forgotten how CSS works. Always double-check this spelling. The other big one is not actually installing the theme. Defining the theme’s name here doesn’t magically download it. You have to do that part yourself. I’m sorry, I don’t make the rules.