Cloudflare Pages builds and hosts a Hugo site for free, with preview deployments on every pull request. The setup is five minutes; the gotchas are all in the Hugo version and the build command.

1. Connect the repo

In the Cloudflare dashboard: Workers & Pages → Create → Pages → Connect to Git. Pick your repo and branch.

2. Set the build configuration

3. Pin your Hugo version

This is the gotcha that breaks the most builds. Cloudflare’s default Hugo version may not match what you’re running locally, and Hugo’s template syntax and module behavior change between versions — especially Extended vs non-Extended (which affects Sass/SCSS support).

Set it explicitly as an environment variable in the Pages project settings:

HUGO_VERSION=0.140.0

Check your local version first so they match:

hugo version

If you use Sass/SCSS (most Hugo themes do), you need the Extended version. Cloudflare’s Hugo builds are Extended by default, but if your local Hugo isn’t, you’ll get inconsistent behavior between local and deployed builds.

4. Custom domain

Pages project → Custom domains → Add. If your domain is already on Cloudflare DNS, it’s a one-click CNAME setup. If it’s elsewhere, you’ll add a CNAME record pointing to <project>.pages.dev.

TLS provisions automatically, usually within a few minutes.

5. Preview deployments

Every push to a non-production branch gets its own preview URL automatically — https://<hash>.<project>.pages.dev. Every pull request gets a comment with its preview link. No extra config needed; this is on by default once the project is connected to Git.

Gotchas

Future-dated posts silently vanish. Hugo excludes posts with a future date from the build unless you pass --buildFuture. If a post doesn’t show up after deploy and there’s no error, check the date first:

hugo --buildFuture --minify

Don’t add --buildFuture to your production build command unless you actually want scheduled-future posts live immediately — it defeats the purpose of scheduling.

Draft posts need --buildDrafts. Same failure mode: a post with draft = true in its front matter builds silently to nothing, no error, no warning. Grep your content directory if a post is missing:

grep -rl "draft = true" content/

Module-based themes need HUGO_ENV=production and sometimes a go.mod. If your theme is a Hugo Module rather than a git submodule, make sure hugo mod vendor runs, or the build command needs to be hugo --minify with Go available in the build image — Cloudflare’s Hugo preset includes Go, but a custom build command might not use it correctly.

Build output directory mismatch. If you changed publishDir in hugo.toml, update the Pages build output directory to match — it defaults to public and won’t find your files otherwise, failing with a blank deploy and no clear error beyond “no files to publish.”