Cloudflare Pages: Deploying a Hugo Site

Today, Cloudflare annouced general availability of the Cloudflare Pages service. I was excited about migrating away from AWS S3 static site and found the process to be pretty easy with one potential problem.

Cloudflare has a new service for the building and deployment of static sites called Cloudflare Pages. The basic idea is that you can deploy a static site to Cloudflare and have it automatically update when you make changes to your site.

After linking my repository to the Cloudflare Pages service, I found that the build of Hugo build failed. In typical Hugo fashion, the error is a little cryptic.

Error: "/opt/buildhome/repo/themes/uBlogger/layouts/shortcodes/admonition.html:4:1": parse failed: template: shortcodes/admonition.html:4: function "merge" not defined

Hugo is a great static site generator. The frequent updates have given the community many new functions, but older versions of Hugo will fail to build if the site uses these new features. New functions aren’t a problem specific to Cloudflare Pages. Many platforms and Linux distributions include legacy versions of Hugo. Thankfully, Cloudflare has an easy way to choose the version of Hugo to use.

In the new site creation page in Cloudflare pages, under the “Advanced” section “Environment Variables,” you can choose the version of Hugo to use. Set HUGO_VERSION to “0.88.1” or the other Hugo version you want to use.

With this small change, the site builds and deploys quickly.