A Complete Tutorial: Deploying Hugo to Cloudflare Pages

Leeting Yan

Cloudflare Pages is a fast, reliable, and developer-friendly platform for deploying static sites. It integrates naturally with GitHub, offers global CDN distribution, and supports full JAMstack workflows. Hugo, being one of the fastest static site generators available, pairs perfectly with Cloudflare Pages.

In this guide, we walk through the full workflow—building, connecting, deploying, enabling custom domains, and ensuring your site performs consistently across the Cloudflare network.

1. Why Use Cloudflare Pages for a Hugo Site?

Cloudflare Pages provides several strengths that align well with Hugo:

  • Global CDN by default
  • Fast deployments and previews
  • Zero configuration for static sites
  • Automatic HTTPS via Cloudflare-managed SSL
  • Integrated caching and edge performance
  • Serverless function support (Pages Functions)
  • Tight GitHub/GitLab integration

If your site values speed, uptime, and simplicity—Cloudflare Pages is an excellent fit.

2. Requirements and Local Setup

Before deploying, ensure you have:

  • Git installed
  • A GitHub (or GitLab) account
  • Hugo installed locally
  • A Cloudflare account

Verify your Hugo version:

hugo version

You should see a version number output (extended version recommended for SCSS/asset pipelines).

3. Create or Prepare Your Hugo Project

You can create a new project:

hugo new site my-hugo-site

Or use an existing Hugo site.

Add a theme or your own layouts. For example, using the Ananke theme:

cd my-hugo-site
git init
git submodule add [https://github.com/theNewDynamic/gohugo-theme-ananke](https://github.com/theNewDynamic/gohugo-theme-ananke) themes/ananke
echo 'theme = "ananke"' >> config.toml

Commit your work:

git add .
git commit -m "Initial Hugo site"

Push to GitHub (or GitLab):

git remote add origin [https://github.com/yourname/my-hugo-site.git](https://github.com/yourname/my-hugo-site.git)
git push -u origin main

4. Connect the Repository to Cloudflare Pages

  1. Log in to Cloudflare
  2. Go to Pages → Create a Project
  3. Choose Connect to Git
  4. Select your Hugo repository
  5. Configure build settings:

Build command:

hugo

Build output directory:

public

Environment variables:
Cloudflare Pages currently requires explicit Hugo version declaration:

HUGO_VERSION = 0.134.2     # Use your preferred version
HUGO_ENV = production

Click Save and Deploy.

Cloudflare Pages will:

  • clone your repo
  • install Hugo
  • build your site
  • distribute it to the global CDN

You will be given a temporary *.pages.dev domain.

5. Validate the Build

Your first deployment typically takes less than a minute.
Open the deployment URL to confirm everything works.

If you see:

  • styles missing
  • theme issues
  • 404 errors

Check that:

  • your theme is included via Git submodule or vendor directory
  • baseURL is correct in config.toml
  • theme path is correct (e.g., theme = "ananke")

6. Adding a Custom Domain

To use your own domain:

  1. Go to Pages → Your Project → Custom Domains
  2. Click Set Up Custom Domain
  3. Enter your domain (e.g., example.com)
  4. Add required DNS records (Cloudflare will guide you)

Typically:

CNAME   example.com → your-site.pages.dev

Cloudflare will automatically issue SSL.

If your domain already uses Cloudflare DNS, changes appear instantly.

7. Enabling Automatic Deployment Previews

Cloudflare Pages creates “Preview Deployments” for every pull request.

This gives you:

  • live URLs for PRs
  • easy QA for content and theme updates
  • safe collaboration across teams

No configuration required—just open a PR.

8. Enabling Hugo Extended Features (SCSS, Pipes)

If your build depends on SCSS or Hugo Pipes:

Set:

HUGO_VERSION = 0.134.2
HUGO_ENV = production

Cloudflare automatically installs the extended version when available.

If using PostCSS:

Enable:

NPM_VERSION = latest

Add postcss.config.js + package.json.

9.1 Enable Cloudflare Cache

Cloudflare Pages already uses CDN caching, but you can strengthen it:

  • enable Caching Level: Standard
  • enable Browser Cache TTL (e.g., 4 hours)
  • use Transform Rules to add Cache-Control headers

Example header:

Cache-Control: public, max-age=31536000, immutable

For fingerprinted assets (CSS/JS with hashes), this is ideal.

10. Adding Serverless Logic (Optional)

Cloudflare Pages supports Pages Functions using the Workers platform.

Create:

/functions/api/hello.js

Content:

export async function onRequest(context) {
  return new Response("Hello from Cloudflare Pages Functions!");
}

Deploy again, and your endpoint will be live at:

/api/hello

This is useful for:

  • form handlers
  • dynamic API proxies
  • simple authentication flows
  • newsletter integrations
  • KV database access

11. Using Cloudflare KV, R2, and D1 (Optional)

Cloudflare integrates well with persistent storage:

  • KV for key-value data
  • R2 for object storage
  • D1 for SQLite-compatible databases
  • Durable Objects for stateful logic

A Hugo site can remain fully static while supplementing dynamic features with these services.

12. Local Testing with Cloudflare’s Wrangler (Optional)

Install Wrangler:

npm install -g wrangler

Run Pages locally:

wrangler pages dev

This simulates:

  • CDN routing
  • serverless functions
  • environment variables

Useful for verifying dynamic logic.

13. Handling Common Issues

13.1 Missing Theme

Ensure the theme is included via:

git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

or vendor directory.

13.2 Wrong baseURL

Cloudflare Pages does not require trailing slashes.
In config:

baseURL = "https://yourdomain.com/"

13.3 Build Fails

Check:

  • upstream Hugo version
  • case-sensitive paths
  • missing archetypes or front matter
  • uncommitted theme files

14. Conclusion

Cloudflare Pages provides an elegant way to deploy Hugo sites: fast builds, global distribution, zero-runtime hosting, and a clean integration with Git-based workflows. Its edge capabilities, serverless functions, and caching architecture make it an excellent choice for content sites, blogs, documentation portals, and fully JAMstack applications.

If your goal is to build a simple, fast, and reliable site—Hugo + Cloudflare Pages is one of the best combinations available today.