Deploying Hugo on Cloudflare Pages — Birdor Cloudflare Tutorial Series (Part 3)

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.

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)