Right, so you’ve heard Hugo is “fast.” And it is, preposterously so. We’re talking about building thousands of pages before you can finish saying “Why is my JavaScript framework still installing its dependencies?” But speed is just the shiny lure. The real question is: what are you actually going to catch with this tool? Let’s talk about what it’s brilliant for, and where you might need to… well, manage your expectations.

The Blog: Hugo’s First Love

This is where Hugo cut its teeth, and it shows. Its content engine, particularly the way it handles content in series (like blog posts), is intuitive and powerful. You get built-in pagination, taxonomy (tags and categories), and a straightforward content hierarchy out of the box. The classic blog structure is literally the default. Create a new post with hugo new posts/my-awesome-post.md, and you’re off.

The magic here is front matter. Hugo uses metadata (in YAML, TOML, or JSON) at the top of your content files to understand everything about your content. For a blog, this is your best friend.

---
title: "Why Static Sites are Winning the Internet Back"
date: 2023-10-27
draft: false
tags: ["web-dev", "jamstack", "rant"]
categories: ["Technology"]
summary: "A brief history of how we overcomplicated things for a decade and are finally coming to our senses."
---

Why is this so effective? Because it separates your content from its presentation completely. You write in simple Markdown. Hugo, using your templates, worries about wrapping it in HTML, injecting it into lists, and generating RSS feeds. It’s a content creator’s dream. The only pitfall? Getting your permalinks right. Always set your permalinks structure in your config.toml early to avoid breaking URLs later. Trust me on this.

Documentation: Structure and Scale

If you think building a blog is neat, wait until you see it handle a complex documentation site. This is where Hugo’s sections and archetypes truly shine. You can create a perfectly organized docs folder with nested sections like docs/getting-started/installation.md and docs/advanced/deployment/kubernetes.md.

You’ll use an archetype to ensure every new doc page has the right front matter. Create a file at archetypes/docs.md:

---
title: "{{ replace .Name "-" " " | title }}"
weight: 10
description: ""
keywords: []
---

Now, running hugo new docs/my-new-feature.md creates a pre-populated file with a sensible title and, crucially, a weight parameter. This weight is how you control the order of pages in your navigation sidebar, which is infinitely more manageable than trying to sort by filename or date. The best practice here is to use multiples of 10 (e.g., 10, 20, 30…) so you can slot new pages in between later without renumbering your entire site. It’s a simple trick that saves a colossal amount of frustration.

The Marketing Site: Beyond the Blog

Not every site is a chronological stream of thoughts. Sometimes you need a handful of meticulously crafted pages: Home, Features, Pricing, About. Hugo handles this with ease using its page types. You can create a content/ directory that looks like this:

content/
├── _index.md         # The home page
├── about.md
├── pricing.md
└── blog/             # The blog section
    ├── _index.md
    └── posts/...

The key here is the _index.md file. It’s the landing page for a section (like /blog/) or the root of your entire site (/). This is where you’d put the content for your homepage. For a “Features” page with a list of sub-features? Create a features/ section with an _index.md for the main landing page and individual feature-one.md, feature-two.md files as regular pages within that section. This structure gives you immense flexibility to mix list pages (which use a list.html template) and single pages (which use a single.html template) exactly where you need them.

And Yes, Even Books

This one surprises people, but Hugo is a fantastic tool for authoring long-form, linear content like a book or course. The trick is to use the NextInSection and PrevInSection page variables. By carefully setting the weight of each chapter in your front matter, you can build a perfect “Next Chapter” / “Previous Chapter” navigation.

{{/* In your single-page template for a chapter */}}
<article>
    <h1>{{ .Title }}</h1>
    {{ .Content }}
</article>
<nav>
    {{ with .NextInSection }}
        <a href="{{ .Permalink }}">← {{ .Title }}</a>
    {{ end }}
    {{ with .PrevInSection }}
        <a href="{{ .Permalink }}" style="float: right;">{{ .Title }} →</a>
    {{ end }}
</nav>

The rough edge? This isn’t a dedicated publishing platform. There’s no built-in concept of a “table of contents” object, so generating a full TOC page requires a bit more manual work, often by using .Pages to range through a section. It’s absolutely doable, but it’s not a one-command solution. You have to build it, which is both Hugo’s greatest strength and occasional weakness: it gives you the blocks, but you have to be the architect.