Hugo bills itself as “the world’s fastest static site generator,” and after using it for a few projects I think that’s a fair claim — both in terms of build speed and how quickly you can go from zero to a working site.

This post walks through what it actually takes to get a Hugo site up and running.

Prerequisites

You’ll need Hugo installed. The recommended way on macOS is via Homebrew:

brew install hugo

On Linux, grab the latest binary from the Hugo releases page or use your distro’s package manager.

Verify the install:

hugo version

Creating a New Site

hugo new site my-site
cd my-site

This scaffolds the directory structure Hugo expects:

my-site/
├── archetypes/      # Content templates
├── content/         # Your Markdown files
├── data/            # Structured data (JSON, TOML, YAML)
├── layouts/         # HTML templates
├── static/          # Static assets (copied as-is)
├── themes/          # Installed themes
└── hugo.toml        # Site configuration

Adding Content

Create your first post:

hugo new posts/my-first-post.md

Hugo uses the archetype at archetypes/default.md to populate the front matter. Edit the file and set draft: false when you’re ready to publish.

Running the Dev Server

hugo server -D

The -D flag includes draft content. The server watches for file changes and rebuilds instantly — typically in under 10ms for small sites.

Building for Production

hugo --gc --minify

This outputs the built site to ./public/. The --gc flag cleans up unused cache files, and --minify reduces HTML/CSS/JS output size.

Deployment

The public/ directory is a self-contained static site — no server-side runtime required. You can host it anywhere that serves static files: GitHub Pages, Netlify, Cloudflare Pages, an S3 bucket, or your own VPS.

For GitHub Pages, a simple Actions workflow handles the build and deploy automatically. I’ll cover that in a follow-up post.

Key Things to Know

Front matter is the YAML (or TOML) block at the top of each content file. It’s how you set metadata like title, date, tags, and draft status.

Taxonomies are how Hugo organizes content by tags, categories, or custom groupings. They work automatically once configured.

Shortcodes are Hugo’s way of embedding reusable snippets in Markdown — great for things like figures, code tabs, or callout boxes.

Hugo’s documentation is thorough and well-organized. Once you understand the content/layout/data separation, most things click into place quickly.