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
- Log in to Cloudflare
- Go to Pages → Create a Project
- Choose Connect to Git
- Select your Hugo repository
- 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
baseURLis correct inconfig.toml- theme path is correct (e.g.,
theme = "ananke")
6. Adding a Custom Domain
To use your own domain:
- Go to Pages → Your Project → Custom Domains
- Click Set Up Custom Domain
- Enter your domain (e.g.,
example.com) - 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. Improving Performance: Recommended Settings
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-Controlheaders
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.