Deploying Hugo on Cloudflare Pages — Birdor Cloudflare Tutorial Series (Part 3)
Leeting Yan
Hugo remains one of the fastest and most reliable static site generators available. Cloudflare Pages, with its global CDN and integrated serverless features, provides a perfect home for Hugo websites — from blogs and documentation to developer tools and knowledge bases.
This tutorial walks through the complete Hugo + Cloudflare Pages workflow using Birdor’s calm, developer-friendly style. By the end, you’ll have a solid, stable deployment pipeline with previews, HTTPS, and optional serverless logic.
1. Why Cloudflare Pages Is an Excellent Fit for Hugo
Cloudflare Pages offers:
- automatic global CDN distribution
- fast builds powered by Cloudflare’s network
- seamless GitHub/GitLab integration
- automatic HTTPS with managed certificates
- preview deployments for every branch
- Pages Functions (serverless) for dynamic behavior
- low or zero operational overhead
For Hugo users, this combination provides a fast, predictable, and low-maintenance publishing workflow.
2. Local Hugo Project Setup
2.1 Create a new Hugo site
hugo new site my-hugo-site
Or use an existing project.
2.2 Add a theme (example: Ananke)
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
2.3 Commit the project
git add .
git commit -m "Initial Hugo site"
2.4 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
Your repository is now ready for Cloudflare Pages.
3. Creating a Cloudflare Pages Project
Step 1: Log in to Cloudflare
Go to Pages → Create a Project.
Step 2: Select “Connect to Git”
Choose GitHub or GitLab.
Step 3: Pick your Hugo repository
Cloudflare will read your repo contents.
Step 4: Configure build settings
Build command:
hugo
Build output directory:
public
Environment variables:
Cloudflare supports custom Hugo versions.
HUGO_VERSION = 0.134.2
HUGO_ENV = production
(Replace with your desired version.)
Step 5: Deploy
Click Save and Deploy.
Cloudflare will:
- clone your repository
- install Hugo
- build the site
- deploy to a global CDN
- generate
<project>.pages.devdomain
Deployment typically takes under a minute.
4. Validating the Deployment
Visit:
https://<project>.pages.dev
If you see:
- missing styles
- incorrect links
- missing theme assets
check:
- the theme is committed (submodule or vendor folder)
baseURLinconfig.tomlends with/- theme path is correct
Example config.toml snippet:
baseURL = "[https://example.com/](https://example.com/)"
theme = "ananke"
5. Adding a Custom Domain
Cloudflare makes this simple.
Step 1: Go to your Pages project
Step 2: Open Custom Domains
Step 3: Add domain (e.g., mydomain.com)
Step 4: Cloudflare auto-creates DNS records
Usually:
CNAME mydomain.com → yourproject.pages.dev
Cloudflare handles SSL certificates automatically.
Propagation is nearly instant when using Cloudflare DNS.
6. Deployment Previews (Branch Previews)
Whenever you push a new branch or open a pull request, Cloudflare Pages creates:
- an isolated preview environment
- a unique preview URL
- a separate preview cache
This makes it easy to test:
- content changes
- theme updates
- layouts and partials
- CSS/JS refactors
This workflow is ideal for open-source or team projects.
7. Environment Variables (For Advanced Builds)
Cloudflare Pages supports build-time environment variables.
Examples:
HUGO_VERSION = 0.134.2
HUGO_ENV = production
NODE_VERSION = 20
Useful for:
- SCSS pipelines
- PostCSS
- API keys (build-time only)
- third-party integrations
Note: these are not available in the browser — they are evaluated at build time.
8. Using SCSS, PostCSS, or Hugo Pipes
Cloudflare’s build environment supports Hugo Extended.
To ensure compatibility:
HUGO_VERSION = <extended-version>
For PostCSS:
NPM_VERSION = latest
Then include:
postcss.config.jspackage.jsonpackage-lock.json
Cloudflare will automatically install and execute PostCSS plugins.
9. Adding Serverless Logic with Pages Functions
Cloudflare Pages supports Functions using Cloudflare Workers’ runtime.
Example: functions/api/hello.js
export async function onRequest(context) {
return new Response("Hello from Cloudflare Pages Functions!");
}
This creates a live endpoint:
/api/hello
Use cases:
- contact forms
- dynamic content
- webhook receivers
- authentication gates
- small API utilities
- personalization logic
Hugo + Functions = a complete, globally distributed JAMstack app.
10. Improving Performance with Cloudflare
Cloudflare already caches static assets by default.
To optimize further:
- use hashed filenames for JS/CSS
- set long-lived cache headers
- serve images in WebP/AVIF (Cloudflare can auto-optimize)
- use Brotli compression
- enable
Always Use HTTPS
Caching rules can be configured in:
Rules → Page Rules / Cache Rules / Transform Rules
Cloudflare’s edge network ensures your Hugo site loads consistently fast worldwide.
11. Recommended Best Practices for Hugo on Pages
- always define
baseURL - avoid
.gitignore-ing themes by accident - use fingerprinted assets for caching
- enable DNSSEC
- use custom domains for production
- keep Hugo version pinned
- use branch previews for QA
- avoid unnecessary build complexity
Cloudflare Pages removes most of the operational overhead — lean into that simplicity.
12. Conclusion and What’s Next
In this chapter, we built a complete Hugo → Cloudflare Pages deployment workflow:
- Git-connected repo
- fast automatic builds
- CDN-backed hosting
- HTTPS and custom domains
- branch previews
- optional Pages Functions for dynamic logic
With this setup, your Hugo site benefits from global performance and minimal maintenance.
Next chapter:
Cloudflare Tutorial Series — Part 4: CDN, Caching, and Edge Rules (A Practical Guide)