↓ Skip to main content

Step-by-Step Guide to Deploying Hugo on Cloudflare Pages with Custom Headers

Deploying Hugo on Cloudflare Pages with Custom Security Headers

I spent a weekend getting a Hugo site compiled down to clean static HTML, deployed it, and then actually looked at the response headers coming back. Nothing. No CSP, no HSTS, referrer data leaking on every outbound link, static assets serving with whatever default cache headers the host felt like giving me. The site itself was fast. The edge around it was wide open.

Cloudflare Pages fixes the hosting half of that automatically — global CDN, free SSL, Git-triggered builds — but none of that touches your security headers by default. That part you have to build yourself, and it’s worth doing right the first time instead of bolting it on after something goes wrong.

How the Pipeline Actually Works
#

Three stages, worth understanding before you touch the dashboard. You push to main. Cloudflare pulls the repo, spins up a clean Ubuntu build container, installs whatever Hugo version you told it to, and compiles your markdown down into public/. Then it reads everything in that output directory — including any security rules you’ve defined — and pushes the whole thing out across its edge network in roughly the time it takes to read this sentence.

Component Role Why it matters
Hugo Static site generator Compiles markdown to dependency-free HTML/CSS
Cloudflare Pages Edge hosting + CI/CD Global CDN, automatic SSL, Git-linked builds
_headers file Edge security policy Injects HTTP security headers at the edge itself

Step 1: Pin Your Hugo Version
#

Cloudflare’s build container doesn’t know what Hugo version your site actually needs unless you tell it. Leave it on defaults and you risk pulling a version that silently breaks a shortcode or your asset pipeline on the next platform update. Your hugo.toml stays standard:

baseURL = 'https://example.com/'
languageCode = 'en-us'
title = 'My Site'
theme = 'your-theme-name'

The version pin itself happens in the Cloudflare dashboard, not in this file — that’s the next step.

Step 2: Wire Up the Git Pipeline
#

In the Cloudflare dashboard: Workers & Pages → Pages → Create application → Connect to Git. Pick your repo, grant read access, then set the build config exactly:

  • Production branch: main
  • Framework preset: Hugo
  • Build command: hugo --minify
  • Build output directory: public

Then under Environment Variables, add:

  • HUGO_VERSION → whatever version you’re actually running locally (check with hugo version before you set this — don’t guess)
  • NODE_VERSION → 20, only if you’re running Tailwind or PostCSS as part of the build

Save and deploy. Cloudflare pulls, builds with your pinned version, and the site goes live on a *.pages.dev subdomain automatically.

Step 3: The _headers File
#

This is the part that actually closes the gap. Cloudflare Pages reads a file named _headers sitting in your build output root and applies whatever rules it finds at the edge, before the request even reaches your actual HTML. Hugo copies everything from static/ straight into public/ on build, so the file belongs at static/_headers in your project:

nano static/_headers

Step 4: The Headers Manifest
#

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  X-XSS-Protection: 1; mode=block
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()
  Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https:; connect-src 'self';

/css/*
  Cache-Control: public, max-age=31536000, immutable

/js/*
  Cache-Control: public, max-age=31536000, immutable

/images/*
  Cache-Control: public, max-age=31536000, immutable

/fonts/*
  Cache-Control: public, max-age=31536000, immutable

Walking through what each piece actually buys you: X-Frame-Options: DENY stops your site from being loaded inside someone else’s iframe for a clickjacking setup. Strict-Transport-Security with max-age=63072000 forces two years of HTTPS-only on return visits — preload on top of that submits you to the browser preload list so even the first visit skips plaintext HTTP entirely, assuming you’ve actually registered the domain with the preload list separately. The immutable cache rules tell browsers to hold onto CSS, JS, fonts, and images for a full year without re-checking, which cuts edge bandwidth and speeds up repeat visits — just know it means any file at those paths has to change its filename (usually via Hugo’s fingerprinting) if you ever need to force an update, since nothing’s going to re-fetch it otherwise.

One honest caveat on the CSP line specifically, because I don’t want to hand this to you dressed up as airtight when it isn’t quite: 'unsafe-inline' is sitting in both script-src and style-src, and that genuinely weakens what CSP is for. The whole point of a script-src policy is blocking injected inline scripts from executing — unsafe-inline reopens exactly that door. It’s there because a lot of Hugo themes and asset pipelines rely on inline <style> or <script> blocks and break without it. If your theme doesn’t need it, strip it out and lock script-src down to 'self' plus your actual CDN origins. If it does need it, know that you’re trading some real XSS protection for compatibility — that’s a fine trade to make consciously, just don’t mistake the rest of this header block for making it disappear.

Step 5: Verify It’s Actually Live
#

Push the _headers file, let the automatic build run, then check the real response instead of trusting that it worked:

curl -I https://example.com

You’re looking for your headers to show up in the raw response:

HTTP/2 200
date: Wed, 21 Oct 2026 12:00:00 GMT
content-type: text/html; charset=utf-8
x-frame-options: DENY
x-content-type-options: nosniff
strict-transport-security: max-age=63072000; includeSubDomains; preload
content-security-policy: default-src 'self'; script-src 'self'...
cf-cache-status: DYNAMIC
server: cloudflare

If they’re there, the pipeline’s doing its job — every push rebuilds and redeploys with the same hardened edge config automatically, no manual step required after this point. The speed was never the part that needed fixing. It was always everything sitting quietly unprotected around it.

Melvin
Author
Melvin
I am a software developer building high-performance local AI tools and web architectures. I created Sablegrid, a platform that automates project scoping end to end. Stellar Tech Labs is where I write up what I learn along the way.

Related

Comments