🚀 Introduction

In 2026, hosting a Hugo-compiled Markdown static blog on Cloudflare Pages (a.k.a. CF Pages) is still the ultimate “free lunch” combo on the planet. You get global edge delivery with sub-second loads, fully free usage, and unlimited requests/traffic.

However, as Cloudflare pushes forward with a major dashboard redesign and Hugo keeps iterating, plenty of older tutorials have turned into a field of buried landmines. This post is a real, unfiltered account of the full trap-clearing, course-correcting journey.

🎨 Why Hugo?

After comparing the four big static site generators side by side, we landed on Hugo:

  • Hugo (Go): single binary, zero dependencies, microsecond builds, mature ecosystem (the classic, minimal, gorgeous PaperMod theme).
  • Astro / VitePress: modern, but for a pure-Markdown tech blogger, the freedom comes with extra configuration overhead.
  • Hexo (Node.js): great Chinese ecosystem, but heavy dependencies and a steep build-time cliff once you cross a hundred posts.

🛠️ The Core Cheat Sheet: Traps the Old Tutorials Never Warned You About

Trap #1: The new Hugo default security policy gives you a blank page locally

Symptom: After pulling in a theme (e.g. PaperMod) and running hugo server, the page renders as a blank white screen with no error at all.

Fix: Newer Hugo versions ship strict module and exec security restrictions. You have to explicitly grant permissions at the bottom of hugo.toml:

[security]
  [security.exec]
    allow = ['^go$', '^npx$', '^postcss$']
  [security.modules]
    allow = ['os', 'getenv']

Trap #2: Git Submodules “vanish” when cloning a private repo

Symptom: The online build fails with error calling partial: partial "head.html" not found.

Fix:

  1. Make sure the theme’s clone URL in .gitmodules at the project root is in HTTPS form, never SSH (CF doesn’t have your private SSH key):

    [submodule "themes/PaperMod"]
    path = themes/PaperMod
    url = [https://github.com/adityatelange/hugo-PaperMod.git](https://github.com/adityatelange/hugo-PaperMod.git)

  2. You must explicitly set the Cloudflare build env var GIT_SUBMODULES = true to force the build engine to recursively fetch submodules.

Trap #3: The theme refuses to build on Cloudflare’s default Hugo version

Symptom: The CF build log turns red with: ERROR => hugo v0.146.0 or greater is required for hugo-PaperMod to build.

Fix: Cloudflare Pages ships with a fairly old default compiler. You need to pin a modern stable version in the CF environment variables: HUGO_VERSION = 0.150.0.

🤯 The Final Boss: Hide-and-Seek in Cloudflare’s 2026 UI Redesign

This is the most maddening part. In the 2026 Cloudflare dashboard, the old Workers and Pages entry points have been merged together.

1. The Workers rate-limit trap

If you follow the default wizard and click Create application, bind a Git repo, and CF will guide you into the “Create a Worker” flow.

  • Workers’ structural flaw: the free plan hard-caps at 100,000 requests per day. Once your blog has a few images or faces malicious traffic, the site instantly returns 1101 Error and goes down.
  • Pages’ real value: truly unlimited! Pure static edge distribution, immune to DDoS.

2. Find the Pages entry point!

On the “Create a Worker / Select a repository” page, do NOT blindly click the blue Next button!

Scroll the page all the way to the bottom. Hidden in a corner, you’ll find a small line the product manager intentionally tucked away:

“Looking for Cloudflare Pages? Deploy a static site instead”

Click the Pages link in that line to switch back to the real Pages deployment flow!

📝 The Final Cloudflare Perfect Production Config Snapshot

Once you successfully sneak into the real Pages page, make sure your parameters match the ones below exactly.

⚙️ Build configuration

  • Framework preset: Hugo
  • Build command: hugo
  • Build output directory: public
  • Root directory: /

🔐 Variables and secrets

  • HUGO_VERSION = 0.150.0 (lock a newer Hugo to remove the theme’s restriction)
  • GIT_SUBMODULES = true (enable submodule fetching to avoid losing styles)

🎯 Proof of Victory

Config aligned, env vars saved, click Retry deployment.

As the build log scrolls by in a flash, the long-awaited big green checkmark (Success) finally lights up! Cloudflare hands out a brand-new *.pages.dev domain.

At this point, a Hugo tech blog that is fully private source-controlled, zero server cost, unlimited traffic, and globally edge-cached is officially alive.

This post is dedicated to every developer who, while cursing through Cloudflare’s maze-like new UI, refused to give up.