A Journey with Hugo

TLDR;

What is Hugo https://gohugo.io/ - “The world’s fastest framework for building websites”

Here’s the high level steps

Download Hugo binary for your OS
Confirm you can run the hugo binary
Create a new site using hugo
Initiate a new git repository inside your newly provisioned hugo site
Push your new site to github.com
Connect your Github to CloudFlare Pages
Deploy your hugo site to CloudFlare Pages
Test it’s available

Did I try using Docker?
Yes, Docker is the default answer to everything right? I discovered permission issues with the base setup when running hugo new site <newsite>, mounting the path as a volume and then trying to edit it in Visual Studio Code. Am sure there’s a way around this but for these first steps I just wanted a result. Hence the above approach using the locally run Hugo binary on my dev workstation meant permissions where simple and I could get underway quickly.

Here’s the detail

Download Hugo binary for your OS.

https://gohugo.io/installation
Precompiled Binaries here
https://github.com/gohugoio/hugo/releases/tag/v0.145.0

In my case I used the hugo_extended_0.145.0_darwin-universal.tar.gz binary, but do what fits your dev environment.

Extract the binary to a folder

1
2


mkdir hugo_extended
tar -xzvf hugo_extended_0.145.0_darwin-universal.tar.gz -C ./hugo_extended

Confirm you can run the hugo binary

1
2


cd hugo_extended
hugo version

Which should give you this output

1

hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355+extended darwin/arm64 BuildDate=2025-02-26T15:41:25Z VendorInfo=gohugoio

Create a new site using hugo

Run the following hugo command to set up the directory structure and files in the my-new-site folder.

1

hugo new site my-new-site

This will then give the following output if successful

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Congratulations! Your new Hugo site was created in /Users/<yourusername>/Desktop/dev/my-new-site.

Just a few more steps...

1. Change the current directory to /Users/<yourusername>>/Desktop/dev/my-new-site.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

Initiate a new git repository inside your newly provisioned hugo site

Change directory to the my-new-site folder

1

cd my-new-site

Then create a new repository and push it to the main branch

Go to https://github.com and create a new repository my-new-site if you are following along with this guide. Otherwise substitute for your own repository name.

1
2
3
4
5


echo "# my-new-site" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main

This will initalise the repository, add a README.md file and commit the changes to the respositories main branch.

1
2
3
4


Initialized empty Git repository in /Users/andreril/Desktop/dev/my-new-site/.git/
[main (root-commit) 33c6e22] first commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

Push your new site to github.com

1
2


git remote add origin [email protected]:<YOURGITUSERHERE>/my-new-site.git
git push -u origin main

Will give you a result like this

1
2
3
4
5
6
7


Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 225 bytes | 225.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:andrewkriley/my-new-site.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

You can then add the rest of the Hugo created files

1
2


git add .
git commit -m "hugo commit"

Resulting in

1
2
3
4


[main a5a500f] hugo commit
 2 files changed, 8 insertions(+)
 create mode 100644 archetypes/default.md
 create mode 100644 hugo.toml

then

1

git push origin main

Results

1
2
3
4
5
6
7
8


Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 534 bytes | 534.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:andrewkriley/my-new-site.git
   33c6e22..a5a500f  main -> main

UNFINISHED BELOW

Connect your Github to CloudFlare Pages
Deploy your hugo site to CloudFlare Pages
Test its available

Resources used

https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/
https://github.com/CaiJimmy/hugo-theme-stack
https://github.com/CaiJimmy/hugo-theme-stack-starter
https://gohugo.io/installation

Future projects

Publish the docker image for Hugo I created
Publish a how-to using the above and a local docker compose example
CF page with a custom domain