Right, let’s talk about the knobs and levers that actually determine what gets built when you run hugo. This isn’t about content; it’s about the build process itself. Think of it as the instructions you give to the factory foreman (Hugo) before he yells at the assembly line robots to start working. Get this wrong, and you’ll either ship a bloated, half-finished mess or a site that’s missing its most important pages. Let’s get it right.

Minify: Because Your Users Are on Mobile

You should minify. Full stop. It’s 2024. The argument is over. Minification strips out all the unnecessary whitespace, comments, and other cruft from your final HTML, CSS, and JS to make the files as small as possible. This isn’t a ’nice-to-have’; it’s a core part of being a good citizen on the web. Hugo doesn’t just do this; it does it well, and it does it by default, which is frankly brilliant.

The magic is that it happens during the build, so you don’t have to commit ugly, minified code to your repository. You write beautiful, readable source, and Hugo outputs a tightly-packed, optimized final product. The default settings are perfectly sane, but if you need to get into the weeds—maybe you need to preserve a specific comment or tweak a CSS minifier flag—you can. Here’s the straightforward setup:

[build]
  minify = true # This is the default, but it doesn't hurt to be explicit.

Want to get fancy? You can control the minification of specific output formats. This is Hugo showing off, and I’m here for it.

[outputs]
  home = ["HTML", "JSON"] # Minify both the HTML and the JSON for the home page

[minify]
  [minify.html]
    keep conditional comments = true # For those pesky old IE hacks you might still need
  [minify.css]
    keepCSS2 = true # Sometimes you need this for older browsers

The best practice? Leave it on. The pitfall? Turning it off and forgetting why you did it. Your lighthouse score will remind you.

disableKinds: For When You’re Not Using the Whole Toolbox

Hugo is a multi-talented beast. It can build pages, a JSON index for search, a RSS feed, a sitemap, and a whole zoo of other “kinds” of content. But what if you’re just building a simple brochureware site and the thought of an ATOM feed makes you snort with laughter? Enter disableKinds. This is your way of telling Hugo, “Hey, don’t even bother with that stuff.”

This is a performance optimization. If Hugo doesn’t have to render 500 RSS feed pages, your build will finish faster. It’s that simple. The kinds you can disable are: page, home, section, taxonomy, term, RSS, sitemap, robotsTXT, and 404.

Let’s say you’re building a single-page application (SPA) and you only need the home kind and a custom 404 page. You’d disable everything else:

disableKinds = [
  "page",
  "section",
  "taxonomy",
  "term",
  "RSS",
  "sitemap",
  "robotsTXT"
  # We left out 'home' and '404' so those will still be built.
]

Common Pitfall: This is a sledgehammer, not a scalpel. If you disable RSS, no RSS feeds are generated, site-wide. If you disable page, no regular pages are built. This is the number one way to accidentally make your entire site vanish into the ether. Use this setting with extreme prejudice and double-check your build output. I’ve done it. You’ll do it. It’s a rite of passage.

buildDrafts: Your Secret Weapon for Sanity

By default, Hugo doesn’t build pages with draft: true in their front matter. This is one of its best features. It lets you keep unfinished or unpublished content in your source control without it accidentally going live. The buildDrafts flag is the override switch.

You have two ways to use this:

  1. Globally, in your config: A terrible idea for production, but useful for a local dev environment.
  2. Via the command line: The right way to do it. hugo server -D is the classic incantation for “spin up a local server and show me my drafts, please.”
# In your config.toml (usually for a development environment)
buildDrafts = true

But honestly, just use the flag. It’s more explicit. The workflow is perfect: write a draft, run hugo server -D, share the local URL with a colleague for feedback, and then once it’s ready, remove the draft: true flag. It will then be included in the next production build.

Best Practice: Never, ever set buildDrafts = true in your production config file (e.g., config.production.toml). This is how drafts end up on the live internet, followed by a frantic Slack message and a hurried redeploy. Use environment-based configuration to your advantage:

# config.development.toml
buildDrafts = true
buildFuture = true # Show scheduled content too!

# config.production.toml
buildDrafts = false
buildFuture = false

Then, run your local server with hugo server --environment development to automatically pick up the development settings. This separation is what turns a good static site setup into a rock-solid professional workflow. It’s the difference between hoping you got it right and knowing you did.