How to Deploy a Hugo Static Site

Hugo is the fastest static site generator around — it can build thousands of pages in well under a second. It's a single Go binary with no runtime dependencies, which makes both local development and CI builds delightfully simple. Here's how to take a Hugo site to production.

How a Hugo build works

Hugo reads your content (Markdown), applies your theme's templates, and writes a complete static site to the public/ directory:

hugo --minify

The --minify flag compresses HTML, CSS, JS, and JSON output. The result is plain files — no server, no runtime — that any CDN can serve.

Pin your Hugo version

This is the single most important Hugo production tip. Hugo has two editions — standard and extended (the extended version includes Sass/SCSS processing and WebP support). Many themes require the extended edition. And Hugo evolves quickly, so a build that works locally can break in CI if the versions differ.

Pin the exact version your platform uses. Most platforms read a HUGO_VERSION environment variable:

HUGO_VERSION=0.140.0

If your theme uses SCSS, make sure the extended edition is selected. A mismatch here is the most common cause of "works locally, fails on deploy."

The base URL matters

Hugo bakes your site's base URL into generated links, canonical tags, RSS, and the sitemap. Set it correctly for production:

# hugo.toml
baseURL = "https://example.com/"
title = "My Site"

You can also override it at build time:

hugo --minify --baseURL "https://example.com/"

Get this wrong and your CSS may load from the wrong path or your internal links break — a classic symptom of an unstyled deployed site.

Theme management

If your theme is a Git submodule, make sure your build environment fetches submodules:

git submodule update --init --recursive

Many platforms do this automatically, but it's worth confirming — a missing submodule means a missing theme and a broken build.

Deploying on PandaStack (free)

Hugo's output is pure static files, perfect for free edge hosting:

1. 1Connect your Git repository as a static site.
2. 2PandaStack auto-detects Hugo and runs hugo --minify.
3. 3Set HUGO_VERSION to pin your edition and version.
4. 4Add your custom domain — automatic SSL is issued.
5. 5Push — it rebuilds and redeploys with live build logs.

Builds run in fast microVMs, and the free tier includes 5 static sites with 100 GB/month bandwidth (Pro and above are unlimited static).

Common pitfalls

• Version mismatch — pin HUGO_VERSION; Hugo changes fast.
• Standard vs extended — SCSS themes need the extended edition.
• Wrong baseURL — broken styles and links on the deployed site.
• Unfetched theme submodule — missing theme, failed build.
• Wrong output dir — Hugo writes to public, not dist or build.

References

• Hugo hosting & deployment: https://gohugo.io/host-and-deploy/
• Hugo installation (standard vs extended): https://gohugo.io/installation/
• Hugo configuration: https://gohugo.io/getting-started/configuration/
• Hugo baseURL behavior: https://gohugo.io/methods/site/baseurl/
• Hugo Modules & themes: https://gohugo.io/hugo-modules/

---

Hugo builds in milliseconds and PandaStack serves the result from the edge for free — connect your repo, pin HUGO_VERSION, and get automatic SSL on your domain. Deploy at https://dashboard.pandastack.io