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.dev domain

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)
  • baseURL in config.toml ends 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.js
  • package.json
  • package-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.

  • 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)