DEV Community

Cover image for Hugo on Cloudflare Pages: From Laptop to Live
Alan Conlon
Alan Conlon

Posted on Originally published at alanconlon.com

Hugo on Cloudflare Pages: From Laptop to Live

At the end of the last part you had a Hugo site building on your own machine, live-reloading at localhost:1313, and visible to precisely nobody. This part fixes that. By the end of it the site is on the internet, on your own domain, over HTTPS, and set up so that everything you do from then on deploys itself. There are two setup steps that catch almost everyone, and I’ll flag both as we hit them, because I hit them too.

The shape of what we’re building: your site lives in a GitHub repository, Cloudflare Pages watches that repository, and every time you push a change, Pages runs Hugo and publishes the result. Push to deploy. Once it’s wired up you mostly forget it’s there.

Get the site into GitHub

Your site is a folder of text files, which is exactly what git is built for. If you’ve avoided git until now, this is a gentle place to start, because VS Code gives you the whole thing through a panel and you never have to touch the command line if you don’t want to.

Open your site folder in VS Code. Before you commit anything, one file matters: .gitignore. Hugo builds your finished site into a folder called public, and that folder does not belong in the repository. It’s generated output, Cloudflare rebuilds it on every deploy, and committing it just means a pile of noise in your history and, worse, the chance of editing the built copy of a file by mistake instead of the source. I know that last one bites because it bit me: I once spent a while confused about why an edit wasn’t showing up, and it was because there were two copies of the file and I was editing the wrong one. So put public/ in .gitignore before your first commit and save yourself that afternoon.

public/
resources/
.hugo_build.lock

Enter fullscreen mode Exit fullscreen mode

Then, in VS Code’s Source Control panel (the branch icon in the sidebar), you initialise the repository, stage your files, write a commit message, and commit. Create an empty repository on GitHub, private is fine, mine is, and VS Code will offer to publish your local repository straight to it. That’s your source of truth now, backed up and versioned.

Wire up Cloudflare Pages

In the Cloudflare dashboard, go to Workers & Pages and create a Pages project connected to your GitHub repository. This is where the first real gotcha lives, so slow down for the build settings.

Set the build command to hugo and the output directory to public. Straightforward. But here’s the one that’ll waste an hour if you miss it: Cloudflare’s build image ships with whatever Hugo version it was last updated to (0.147 on the current image, far older on legacy ones), and it can change underneath you. An older Hugo can build a modern site wrong or fail outright, and the error won’t say the version is the problem. Pin the version explicitly. Add an environment variable called HUGO_VERSION set to whatever version you’re building with locally (check with hugo version). Mine’s set to a specific number, not left to chance, and it’s the single most important build setting on the page.

Cloudflare Pages build configuration: build command hugo, output directory public, and a HUGO_VERSION environment variable pinned to match your local Hugo. The pinned version is highlighted as the setting people miss.

Pin HUGO_VERSION or Cloudflare builds with a museum piece.

Save it and Cloudflare runs its first build. If the settings are right, a minute or two later your site is live at a your-project.pages.dev address. That URL is ugly and temporary, but seeing it work means the pipeline is sound.

Point your domain at it

The pages.dev address proves it works; your own domain makes it yours. In the Pages project, under custom domains, add your apex domain (example.com) and the www version. If your DNS is already on Cloudflare, this is nearly automatic, Cloudflare adds the records and sorts the certificate itself.

Add both the apex and www, and let one redirect to the other so you’ve got a single canonical home rather than two versions of the site competing. I send www to the bare domain; plenty of people do it the other way, either is fine as long as you pick one. HTTPS you don’t have to think about at all: Cloudflare issues and renews the certificate automatically, and forces HTTP over to HTTPS for you. That last part matters more than it looks, and it’ll make a confusing cameo in a later part (coming soon) when Search Console "reports" the HTTP-to-HTTPS redirect as though it were a fault. It isn’t. File that away.

Now you have a deploy pipeline

Here’s the part that makes the whole setup worth it. From now on, the loop is: edit a post in VS Code, commit, push. Cloudflare sees the new commit, runs Hugo, and your change is live in a minute or two. No uploading files, no FTP, no "which version is on the server" confusion. The repository is the site; pushing is publishing.

It’s worth doing one deliberate test to prove it to yourself. Change something small, a word on the homepage, commit it in VS Code, push, and watch the Deployments list in Cloudflare Pages show a new build appear and go green. Once you’ve seen that happen, you trust it, and you stop thinking about deployment as a separate step at all.

What’s not done yet

You’ve got a live, self-deploying site on your own domain over HTTPS, which is the milestone. What you don’t have yet is much of a site: no real content structure, no design of your own, and none of the harder edges sorted, the security headers, the scheduling, the caching behaviour. Those are the next parts.

The next one (coming soon) is content: how Hugo organises posts, how front matter works, and how tags and series get their own pages without you building them. That’s where the site stops being a technical exercise and starts being a place you actually write.


Originally published at alanconlon.com, where I post practical security, Azure and data write-ups every other Tuesday.

Top comments (0)